sphinx>=2.0and 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.
Install doxygen and exhale for C++ doc building
Make sure you have installed necessary build tools (i.e. g++, python, cmake, flex, bison)
git clone https://github.com/doxygen/doxygen.git cd doxygen mkdir build cd build cmake -G "Unix Makefiles" .. make make install
pip install exhale
Generate API document
Make sure you have installed MegEngine.
pip3 install megengine -f https://megengine.org.cn/whl/mge.html
Make sure you have cloned MegBrain
git clone firstname.lastname@example.org:brain-sdk/MegBrain.git
Run gen_docs/entry.sh to generate HTML files. The script accepts the MegEngine installation and MegBrain clone path as the argument.
./gen_docs/entry.sh $MGB_ROOT $MGE_ROOT(optional)
Note that the RST files generated from python docstring are put under
Start local sphinx service by:
sphinx-serve -b build -p 8000
Write python API document
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_docs/build.sh for more details.
Example python docstring: see gen_docs/example/example.py.
Run doctest in API document
API docstring also contains examples written by doctest. Run the tests by
gen_docs/entry.sh $MGB_ROOT $MGE_ROOT(optional) 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.
Insert C++ doc hyperlink
- For class referencing:
find the class rst file and copy its name and replace the doc with
:ref:`exhale_class_<filename without .rst>`
- For file referencing:
find the file and copy its name and replace the doc with
Process of generate document
Run CI to generate preview link. Manually trigger is required.