Writing documentation¶
SPhinX environment¶
Note
All the documentation generation operation should be in the directory of the docs.
Install the dependencies¶
pip install -r requirements.txt
Generate the html documentation¶
Before generating the documentation, please check the output
path located at line 11 in the make.bat file:
set BUILDDIR=../../data-platform-website/build
Warning
Please pay attention to the extensions in the conf.py file, please comment "sphinx.ext.viewcode" if you do not want to make the source code open.
Generate the html file:
make html
Tutorials¶
Cheatsheet: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
Official documentation: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
Example: NetworkX package
Documentation organization¶
Documentation is very important in the coding process, we should regard documentation as writing paper or report for what we have implemented in our codes. A good organization could help readers understand better. In our documentation, we have each folder for each chapter including:
Introduction: very high-level documentation including some essential system flowcharts, feature introduciton, etc.
Tutorial: walkthrough of the main functions including some essential instructions.
Example: executable examples that are generated from
jupyter notebook.Reference: source codes, etc.
Developer: for the developers.
With this organization, if you want to add a complete feature with
tutorial and examples, you should write an executable jupyternotebook and
add this page to the docs/example, write a tutorial
in docs/tutorial while putting the source code in
docs/reference. To link the high-level tutorial and source code, you should add
essential internal links for the functions and classes.