Documentation for Seldon Core

This directory contains the sources (.md and .rst files) for the documentation. The main index page is defined in source/index.rst. The Sphinx options and plugins are found in the source/conf.py file. The documentation is generated in full by calling make html.

Building documentation locally

To build the documentation, first we need to install Python requirements:

pip install -r requirements_docs.txt

We also need pandoc for parsing Jupyter notebooks, the easiest way to install this is using conda:

conda install -c conda-forge pandoc=1.19

We are now ready to build the docs:

make html

The resulting documentation is located in the _build directory with _build/html/index.html marking the homepage.

Sphinx extensions and plugins

We use various Sphinx extensions and plugins to build the documentation:

• m2r - to handle both .rst and .md
• sphinx.ext.napoleon - support extracting Numpy style doctrings for API doc generation
• sphinx_autodoc_typehints - support parsing of typehints for API doc generation
• sphinxcontrib.apidoc - automatic running of sphinx-apidoc during the build to document API
• nbsphinx - parsing Jupyter notebooks to generate static documentation
• nbsphinx_link - support linking to notebooks outside of Sphinx source directory via .nblink files

The full list of plugins and their options can be found in source/conf.py.