Documentation¶

Sphinx¶

For initialization¶

Initialize requirements of documentation generation:

pip install -r requirements/pypi-doc.txt

Initialize Sphinx project:

mkdir docs && cd docs
sphinx-quickstart

# Tips for the interactive configuration phase
#   Choose the option "Separate sources from build"
#   Reference: https://stackoverflow.com/questions/65829149/what-does-separate-source-and-build-directories-mean

Build HTML:

cd build
make html

For incremental changes¶

As documentation of the current project has already been set up, you can only run ./docs/make-html.sh instead of the previous steps:

#!/bin/bash
source setup.sh

pushd docs
  rm -rf build
  make html SPHINXOPTS="-W"
  make_sphinx_ret_val=$?
  if [ $make_sphinx_ret_val -eq 0 ];then
    echo "Built the Sphinx documentation successfully."
  else
    echo "Sphinx documentation building failed!!!"
  fi
popd

Start the server and view the documentation pages¶

Start the HTTP server on the remote side

cd docs/build/html
python -m http.server 8080 -b localhost

Create an SSH tunneling on the local side, which forwards connections/requests from local to remote (server)

ssh -L 8080:localhost:8080 remote-server

Use RST Files within the Sphinx Documentation¶

Include Markdown¶

For including Markdown files into the Sphinx documentation, this project utilizes m2r2 which needs to be installed through pip:

pip install m2r2

Then in .rst file, use the .. mdinclude:: directive to include Markdown file. The path needs to be relative to the .rst file.

.. mdinclude:: ../../../README.md

Include Code snippets¶

Use the .. literalinclude:: directive to include a code snippet from a script/source file.

For example,

.. literalinclude:: ../../../docs/make-html.sh
  :language: bash

results in:

#!/bin/bash
source setup.sh

pushd docs
  rm -rf build
  make html SPHINXOPTS="-W"
  make_sphinx_ret_val=$?
  if [ $make_sphinx_ret_val -eq 0 ];then
    echo "Built the Sphinx documentation successfully."
  else
    echo "Sphinx documentation building failed!!!"
  fi
popd

Auto-Generation of API Documentations¶

The feature of auto-documentation is realized by various Sphinx extensions and third-party tools.

This project adopts Google-style Python docstrings, Example Google Style Python Docstrings for auto-generation of Python API pages.

The authors would like to thank PyTorch for being an exemplar of documentation.

Reference:

https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/api.html

Python documentation¶

Sphinx can utilize Napoleon for auto-generation of API pages of Python code.

import os
import sys
sys.path.insert(0, os.path.abspath(path_to_python_module_dir))
sys.path.insert(0, os.path.abspath(path_to_python_module2_dir))
...

extensions = [
  ...
  'sphinx.ext.autodoc',   # support for auto-doc generation
  'sphinx.ext.napoleon',  # support for numpy / google style
]

References:

Doxygen documentation¶

This project utilizes Doxygen for auto-generation of API pages of C++ SDK, and breathe for including these pages into the Sphinx documentation.

breathe needs to be installed through pip:

pip install breath

Firstly, XML files are generated:

cd sdk
doxygen Doxyfile-cpp

Then, in conf.py, set up breathe to include the XML generated in the previous step.

extensions = [
  "...",
  "breathe",
]
sdk_name = "..."
breathe_projects = { sdk_name: "../../sdk/doxygen_output/xml/" }
breathe_default_project = sdk_name

Reference:

Protobuf documentation¶

This project uses protoc-gen-doc, an extension of the Protobuf compiler, to automatically generate API pages for Protobuf definitions.

To activate this extension, pass --doc_out argument to protoc.

protoc ... \
    --doc_out ${doc_output_dir} \
    ...

References:

https://github.com/pseudomuto/protoc-gen-doc