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

exit $make_sphinx_ret_val

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

exit $make_sphinx_ret_val

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