Генерация документации ESPnet

Установка

Мы используем sphinx для генерации HTML-документации.

$ cd <espnet_root>
$ pip install -e ".[doc]"
$ pip install -U flake8-docstrings

Проверка стиля с помощью flake8-docstrings

Вы можете проверить правильность стиля ваших строк документации с помощью ci/test_flake8.sh, используя flake8-docstrings. Обратите внимание, что многие существующие файлы были добавлены в чёрный список в скрипте, чтобы по умолчанию избежать этой проверки. Вы можете свободно удалять файлы, которые хотите улучшить.

# in ci/test_flake8.sh

# вы можете улучшить плохо написанные строки документации отсюда
flake8_black_list="\
espnet/__init__.py
espnet/asr/asr_mix_utils.py
espnet/asr/asr_utils.py
espnet/asr/chainer_backend/asr.py
...
"

# --extend-ignore для wip-файлов для flake8-docstrings
flake8 --extend-ignore=D test utils doc ${flake8_black_list}

# белый список файлов, которые должны поддерживать flake8-docstrings
flake8 espnet --exclude=${flake8_black_list//$'\n'/,}

НЕ ДОБАВЛЯЙТЕ НОВЫЕ ФАЙЛЫ В ЭТОТ ЧЁРНЫЙ СПИСОК!

Генерация HTML

Вы можете создать локальный HTML вручную, используя sphinx Makefile

$ cd <espnet_root>
$ ./ci/doc.sh

Откройте doc/build/index.html.

Развёртывание

Когда ваш PR будет объединён с веткой master, наш CI автоматически развернёт ваш sphinx html на сайте https://espnet.github.io/espnet/.