How to update the documentation

We use sphinx to generate the documentation for this project. The documentation project has been initialized properly and we basically just need to update the actual content.

Install dependencies: pip install -r ../requirements/docs.txt.

If we ever change the code structure since last compilation, we may need to regenerate the docstring index:

sphinx-apidoc -f -o . ../openfed
sphinx-apidoc -f -o . ../examples

The command detects the code structure under ../openfed and generates a series of *.rst files, such as openfed.api.rst. However, the docstring would not be compiled until we execute make html later.

We can also update the hand-crafted documents, including intro.rst and tutorial.rst. The openfed.rst is the entry file. We don’t need to modify it unless we want to add more hand-crafted pages or adjust the order in the Contents page.

After completing revision on the .rst files, we would compile the documentation source code:

make clean
make html

The Makefile supports many targets. We choose html because we can easily host the documentation on a remote server:

cd _build/html
python -m http.server