Fix conflict

.gitignore

@@ -16,6 +16,9 @@ __pycache__/
 check_autopep8
 .coverage*
 coverage.xml*
+bats-core/
+shellcheck*
+check_shellcheck*
 
 # recipe related
 egs/*/*/data*

.travis.yml

@@ -47,11 +47,15 @@ script:
   - |
     if $USE_CONDA; then
       source tools/venv/bin/activate
+      cd tools; git clone https://github.com/kaldi-asr/kaldi --depth 1; cd -
+      ./ci/doc.sh
     fi
-    travis-sphinx build --source=doc --nowarn
 
 sudo: false
 
 after_success:
   - bash <(curl -s https://codecov.io/bash)
-  - travis-sphinx deploy
+  - |
+    if $USE_CONDA; then
+      travis-sphinx deploy
+    fi

CONTRIBUTING.md

@@ -45,7 +45,7 @@ If you are not familiar with creating a Pull Request, here are some guides:
 - http://stackoverflow.com/questions/14680711/how-to-do-a-github-pull-request
 - https://help.github.com/articles/creating-a-pull-request/
 
-# Version policy and development branches
+## Version policy and development branches
 
 We basically maintain the `master` and `v.0.X.0` branches for our major developments.
 
@@ -60,10 +60,6 @@ We basically maintain the `master` and `v.0.X.0` branches for our major developm
    recipe related changes periodically (every two months or so).
    This is developed at the `master` branch, and these changes are also reflected to the `v.0.X.0` branch frequently.
 
-## Developing locally with ESPnet
-
-TBD
-
 ## Unit testing
 
 ESPnet's testing is located under `test/`.  You can install additional packages for testing as follows:
@@ -72,23 +68,20 @@ $ cd <espnet_root>
 $ pip install -e ".[test]"
 ```
 
-Then you can run the entire test suite with
+### python
+
+Then you can run the entire test suite using [flake8](http://flake8.pycqa.org/en/latest/), [autopep8](https://github.com/hhatto/autopep8) and [pytest](https://docs.pytest.org/en/latest/) with [coverage](https://pytest-cov.readthedocs.io/en/latest/reporting.html) by
 ``` console
-$ pytest
+./ci/test_python.sh
 ```
 
 To create new test file. write functions named like `def test_yyy(...)` in files like `test_xxx.py` under `test/`.
 [Pytest](https://docs.pytest.org/en/latest/) will automatically test them.
 
-We also recommend you to follow our coding style that can be checked as
-``` console
-$ flake8 espnet test
-$ autopep8 -r espnet test --global-config .pep8 --diff --max-line-length 120 | tee check_autopep8
-$ test ! -s check_autopep8
-```
-
 You can find pytest fixtures in `test/conftest.py`. [They finalize unit tests.](https://docs.pytest.org/en/latest/fixture.html#using-fixtures-from-classes-modules-or-projects)
 
+### bash scripts
+
 You can also test the scripts in `utils` with [bats-core](https://github.com/bats-core/bats-core) and [shellcheck](https://github.com/koalaman/shellcheck).
 
 To test:
@@ -101,6 +94,42 @@ To test:
 
 - [setup.cfg](setup.cfg) configures pytest and flake8.
 - [.travis.yml](.travis.yml) configures Travis-CI.
+- [.circleci/config.yml](.circleci/config.yml) configures Circle-CI.
+
+## Writing new tools
+
+You can place your new tools under
+- `espnet/bin`: heavy and large (e.g., neural network related) core tools.
+- `utils`: lightweight self-contained python/bash scripts.
+
+For `utils` scripts, do not forget to add test scripts under `test_utils`.
+
+### Python tools guideline
+
+To generate doc, do not forget `def get_parser(): -> ArgumentParser` in the main file.
+
+```python
+#!/usr/bin/env python3
+# Copyright XXX
+#  Apache 2.0  (http://www.apache.org/licenses/LICENSE-2.0)
+import argparse
+
+# NOTE: do not forget this
+def get_parser():
+    parser = argparse.ArgumentParser(
+        description="awsome tool",  # DO NOT forget this
+    )
+    ...
+    return parser
+
+if __name__ == '__main__':
+    args = get_parser().parse_args()
+    ...
+```
+
+### Bash tools guideline
+
+To generate doc, support `--help` to show its usage. If you use Kaldi's `utils/parse_option.sh`, define `help_message="Usage: $0 ..."`.
 
 
 ## Writing documentation
@@ -117,12 +146,6 @@ Add the shared link to `utils/recog_wav.sh` or `utils/synth_wav.sh` as follows:
 The model name is arbitrary for now.
 
 
-## Python 2 and 3 portability tips
-
-See matplotlib's guideline https://matplotlib.org/devel/portable_code.html
-We do not block your PR even if it is not portable.
-
-
 ## On CI failure
 
 ### Travis CI
@@ -136,3 +159,7 @@ We do not block your PR even if it is not portable.
 3. open your local terminal and `ssh -p xxx xxx` (check circle ci log for the exact address)
 4. try anything you can to pass the CI
 
+### Codecov
+
+1. write more tests to increase coverage
+2. explain to reviewers why you can't increase coverage

README.md

@@ -31,6 +31,8 @@ and also follows [Kaldi](http://kaldi-asr.org/) style data processing, feature e
   * [Error due to matplotlib](#error-due-to-matplotlib)
 * [Docker Container](#docker-container)
 * [Results](#results)
+  * [ASR results](#asr-results)
+  * [TTS results](#tts-results)
 * [Chainer and Pytorch backends](#chainer-and-pytorch-backends)
 * [References](#references)
 * [Citation](#citation)
@@ -359,27 +361,31 @@ go to docker/ and follow [README.md](https://github.com/espnet/espnet/tree/maste
 
 ## Results
 
+### ASR results
+
 We list the character error rate (CER) and word error rate (WER) of major ASR tasks.
 
-|           | CER (%) | WER (%)  |
-|-----------|:----:|:----:|
-| Aishell dev | 6.0 | N/A |
-| Aishell test | 6.7 | N/A |
-| CSJ eval1 | 5.7 | N/A  |
-| CSJ eval2 | 4.1 | N/A  |
-| CSJ eval3 | 4.5 | N/A  |
-| HKUST dev       | 23.5 | N/A  |
-| Librispeech dev_clean  | N/A |  3.7 |
-| Librispeech dev_other  | N/A |  9.8 |
-| Librispeech test_clean | N/A |  4.0 |
-| Librispeech test_other | N/A | 10.0 |
-| TEDLIUM2 dev  | N/A | 12.2 |
-| TEDLIUM2 test | N/A | 10.4 |
-| WSJ dev93 | 3.2 | 7.0 |
-| WSJ eval92| 2.1 | 4.7 |
+|           | CER (%) | WER (%)  | Pretrained model |
+|-----------|:----:|:----:|:----:|
+| Aishell dev            |  6.0 |  N/A | [link](https://github.com/espnet/espnet/blob/master/egs/aishell/asr1/RESULTS.md#transformer-result-default-transformer-with-initial-learning-rate--10-and-epochs--50) |
+| Aishell test           |  6.7 |  N/A | same as above |
+| CSJ eval1              |  5.7 |  N/A | N/A |
+| CSJ eval2              |  4.1 |  N/A | N/A |
+| CSJ eval3              |  4.5 |  N/A | N/A |
+| HKUST dev              | 23.5 |  N/A | [link](https://github.com/espnet/espnet/blob/master/egs/hkust/asr1/RESULTS.md#transformer-only-20-epochs) |
+| Librispeech dev_clean  |  N/A |  3.7 | [link](https://github.com/espnet/espnet/blob/master/egs/librispeech/asr1/RESULTS.md#pytorch-transformer-accum-grad-8-single-gpu) |
+| Librispeech dev_other  |  N/A |  9.8 | same as above |
+| Librispeech test_clean |  N/A |  4.0 | same as above |
+| Librispeech test_other |  N/A | 10.0 | same as above |
+| TEDLIUM2 dev           |  N/A | 12.2 | [link](https://github.com/espnet/espnet/blob/master/egs/tedlium2/asr1/RESULTS.md#transformer-default) |
+| TEDLIUM2 test          |  N/A | 10.4 | same as above |
+| WSJ dev93              |  3.2 |  7.0 | N/A |
+| WSJ eval92             |  2.1 |  4.7 | N/A |
 
 Note that the performance of the CSJ, HKUST, and Librispeech tasks was significantly improved by using the wide network (#units = 1024) and large subword units if necessary reported by [RWTH](https://arxiv.org/pdf/1805.03294.pdf).
 
+### TTS results
+
 You can access the samples of TTS recips from following links:
 
 - [Single English speaker Tacotron2](https://drive.google.com/open?id=18JgsOCWiP_JkhONasTplnHS7yaF_konr)

ci/doc.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+
+# build sphinx document under doc/
+mkdir -p doc/_gen
+
+# NOTE allow unbound variable (-u) inside kaldi scripts
+export LD_LIBRARY_PATH=${LD_LIBRARY_PATH-}
+set -euo pipefail
+# generate tools doc
+(
+    cd ./utils
+    ../doc/argparse2rst.py ./*.py > ../doc/_gen/utils_py.rst
+)
+
+./doc/argparse2rst.py ./espnet/bin/*.py > ./doc/_gen/espnet_bin.rst
+
+
+find ./utils/*.sh -exec ./doc/usage2rst.sh {} \; | tee ./doc/_gen/utils_sh.rst
+
+# generate package doc
+./doc/module2rst.py espnet ./doc --exclude espnet.bin
+
+# build html
+travis-sphinx build --source=doc --nowarn
+
+touch doc/build/.nojekyll
+

ci/test_python.sh

@@ -1,12 +1,12 @@
 #!/usr/bin/env bash
 
-set -euo pipefail
-
 if ${USE_CONDA:-}; then
     . tools/venv/bin/activate
 fi
 
-flake8 espnet test utils;
+set -euo pipefail
+
+flake8 espnet test utils doc;
 autopep8 -r espnet test utils --global-config .pep8 --diff --max-line-length 120 | tee check_autopep8
 test ! -s check_autopep8
 

ci/test_shell.sh

@@ -17,7 +17,7 @@ fi
 set -euo pipefail
 
 echo "=== run shellcheck ==="
-find ci utils -name "*.sh" -printf "=> %p\n" -execdir shellcheck -Calways -x -e SC2001 -e SC1091 -e SC2086 {} \; | tee check_shellcheck
+find ci utils doc -name "*.sh" -printf "=> %p\n" -execdir shellcheck -Calways -x -e SC2001 -e SC1091 -e SC2086 {} \; | tee check_shellcheck
 find egs -name "run.sh" -printf "=> %p\n" -execdir shellcheck -Calways -x -e SC2001 -e SC1091 -e SC2086 {} \; | tee -a check_shellcheck
 if grep -q "SC[0-9]\{4\}" check_shellcheck; then
     echo "[ERROR] shellcheck failed"

doc/.gitignore

@@ -0,0 +1,3 @@
+_gen/
+_build/
+build/

doc/Makefile

@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/README.md

@@ -13,21 +13,12 @@ $ pip install -e ".[doc]"
 
 You can generate local HTML manually using sphinx Makefile
 
-```sh
-$ cd <espnet_root>/doc
-$ make html
-```
-
-`index.html` will be created at `doc/_build/html/index.html`
-
-or using travis-sphinx
-
 ```sh
 $ cd <espnet_root>
-$ travis-sphinx build --source=doc --nowarn
+$ ./ci/doc.sh
 ```
 
-`index.html` will be created at `doc/build/index.html`
+open `doc/build/html/index.html`
 
 ## Deploy
 

doc/apis/espnet_bin.rst

@@ -0,0 +1,8 @@
+.. _core tools:
+
+core tools
+==========
+
+ESPnet provides several command-line tools for training and evaluating neural networks (NN) under ``espnet/bin``:
+
+.. include:: ../_gen/espnet_bin.rst

doc/apis/utils_py.rst

@@ -0,0 +1,8 @@
+.. _python utility tools:
+
+python utility tools
+====================
+
+ESPnet provides several command-line python tools under ``utils/``
+
+.. include:: ../_gen/utils_py.rst

doc/apis/utils_sh.rst

@@ -0,0 +1,9 @@
+.. _bash utility tools:
+
+bash utility tools
+==================
+
+ESPnet provides several command-line bash tools under ``utils/``
+
+.. include:: ../_gen/utils_sh.rst
+