Building Sphinx Doc

Prerequisites

This documentation uses Sphinx third-party Python package. To generate it locally from the docs/sphinx_docs/ folder, you need to install additional components as described in the Section System-wide configuration. Alternatively you can use Docker to setup the required environment into a container to build the documentation, see Section Docker configuration.

System-wide configuration

Install Python

To install python, you can install for example the Anaconda package or the python offical package. You can also install the packages directly from Ubuntu terminal:

apt-get install python3
apt-get install python3-pip

Install Sphinx

From the prompt, it is possible to install Sphinx, as well as additional libraries required for building this documentation using pip:

pip3 install sphinx
pip3 install sphinx_rtd_theme
pip3 install sphinx-numfig
pip3 install sphinxcontrib-bibtex

Install LaTeX

If you want to build PDF, you will need LaTeX installed:

apt-get install texlive
apt-get install texlive-latex-extra
apt-get install latexmk

Building html doc

To build the documentation as a webpage (as shown on ECOGEN website), move to the docs folder and run under prompt:

make html

This will generate a folder docs/build/html containing html source files, open any file with a browser to see generated content.

Building PDF doc

To build the documentation as a PDF, move to the docs folder and run under prompt:

make latexpdf

This will generate a folder docs/build/latex containing source files in LaTeX that can be used to generate a PDF.

Docker configuration

cd docs/sphinx-docs/
# Build the container image using the Dockerfile
docker image build -t sphinx-doc .
# To generate html ouput run
docker container run --mount type=bind,source=${PWD},target=/home sphinx-doc html
# To generate PDF ouput run
docker container run --mount type=bind,source=${PWD},target=/home sphinx-doc pdf

Learning Sphinx

To learn how to develop a documentation using Sphinx, here are some useful links: