ESPnet 文档生成

不到1分钟

ESPnet文档生成

安装

We use sphinx to generate HTML documentation.

# Clean conda env for docs
$ cd <espnet_root>
$ conda create -p ./envs python=3.10
$ conda activate ./envs

# Requirements
$ pip install -e ".[all]"
$ pip install -e ".[doc]"
$ conda install conda-forge::ffmpeg
$ conda install conda-forge::nodejs==22.6.0

# (Optional requirement) To use flake8-docstrings
$ pip install -U flake8-docstrings

如果您使用了上述干净的conda环境，您需要编写自己的. tools/activate_python.sh。示例如下：

#!/usr/bin/env bash

# You might check $CONDA_EXE to find the <conda_root>
. <conda_root>/miniconda/etc/profile.d/conda.sh && conda activate <espnet_root>/envs

使用flake8-docstrings进行代码风格检查

你可以通过使用flake8-docstrings运行ci/test_flake8.sh来检查你的文档字符串风格是否正确。请注意，脚本中默认已将许多现有文件添加到黑名单以避免此项检查。你可以自由移除想要改进的文件。

# in ci/test_flake8.sh

# you can improve poorly written docstrings from here
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 for wip files for flake8-docstrings
flake8 --extend-ignore=D test utils doc ${flake8_black_list}

# white list of files that should support flake8-docstrings
flake8 espnet --exclude=${flake8_black_list//$'\n'/,}

请勿向此黑名单添加新文件！

Generate HTML

您可以使用sphinx的Makefile生成并测试网页。

$ cd <espnet_root>
$ ./ci/doc.sh
$ npm run docs:dev

部署

When your PR is merged into master branch, our CI will automatically deploy your sphinx html into https://espnet.github.io/espnet/.