Writing documentation

Section author: Xingmin Wang <xingminw@umich.edu>

SPhinX environment

Note

All the documentation generation operation should be in the directory of the docs.

Install the dependencies

• Install packages:

pip install -r requirements.txt

• Install Pandoc: [download].

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

• Theme docs: https://sphinx-book-theme.readthedocs.io/en/latest/

• Cheatsheet: https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html

• Official documentation: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html

• Example: EBP

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:

• Overview: introduction 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 examples.rst, 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.