-
Install
sphinx>=2.0
and related dependencies by:pip3 install -U sphinx sphinx-autodoc-typehints sphinx-serve sphinxcontrib-jupyter nbsphinx jieba pip3 install git+https://github.com/pandas-dev/pydata-sphinx-theme.git@master
-
reStructuredText (RST) is used for document writing. HTML files can be generated from the RST files for document visualization.
For more information about RST, please visit https://sphinx-doc-zh.readthedocs.io/en/latest/rest.html.
-
Make sure you have installed MegEngine.
pip3 install megengine -f https://megengine.org.cn/whl/mge.html
-
Run gen_python_docs/gendoc.sh to generate HTML files. The script accepts the previous python
site-packages
directory as the argument. Default value is~/.local/lib/python3.6/site-packages
. Note that the RST files generated from python docstring are put undersource/autogen
../gen_python_docs/gendoc.sh ~/.local/lib/python3.6/site-packages
-
Start local sphinx service by:
sphinx-serve -b build -p 8000
-
How documents are generated for python codes
- Write comments following docstring rules.
- Run sphinx tool to generate RST files from python docstring.
- Generate HTML files from RST.
Refer to gen_python_docs/gendoc.sh for more details.
-
Example python docstring: see gen_python_docs/example/example.py.
API docstring also contains examples written by doctest. Run the tests by
gen_python_docs/gendoc.sh ~/.local/lib/python3.6/site-packages
sphinx-build -b doctest source build/doctest
If all tests are passed, you shall see the following similar printouts:
Doctest summary
===============
16 tests
0 failures in tests
0 failures in setup code
0 failures in cleanup code
build succeeded.
Otherwise, please fix any failed test or warning.