5. Generate Documentation#

The documentation consists of a Doxygen documentation and a Sphinx documentation. You should generate the Doxygen documentation first. Before generating the Sphinx documentation, you should compile the package.

Get the source code from the GitHub repository.

git clone https://github.com/ameli/imate.git
cd imate

If you already had the source code, clean it from any previous build (especially if you built in-source):

python setup.py clean

5.1. Generate Doxygen Documentation#

Install doxygen and graphviz by

sudo apt install doxygen graphviz -y

sudo yum install doxygen graphviz -y

sudo dnf install doxygen graphviz -y

sudo brew install doxygen graphviz -y

scoop install doxygen graphviz

Attention

Make sure you ran python setup.py clean as mentioned previously. Otherwise, if the source directory is not cleaned from any previous built (if there is any), Doxygen unwantedly generates all auto-generated cython files.

Generating the Doxygen documentation by

cd docs/doxygen
doxygen doxyfile.in
cd ../..

5.2. Compile Package#

Set CYTHON_BUILD_FOR_DOC to 1 (see Configure Compile-Time Environment variables). Compile and install the package by

export CYTHON_BUILD_FOR_DOC=1
export USE_CUDA=0
sudo -E python setup.py install

$env:CYTHON_BUILD_FOR_DOC = "1"
$env:USE_CUDA = "0"
sudo -E python setup.py install

5.3. Generate Sphinx Documentation#

Install Pandoc by

sudo apt install pandoc -y

sudo yum install pandoc -y

sudo dnf install pandoc -y

sudo brew install pandoc -y

scoop install pandoc

Install the requirements for the Sphinx documentation by

python -m pip install -r docs/requirements.txt

The above command installs the required packages in Python’s path directory. Make sure python’s directory is on the PATH, for instance, by

PYTHON_PATH=`python -c "import os, sys; print(os.path.dirname(sys.executable))"`
export PATH=${PYTHON_PATH}:$PATH

$PYTHON_PATH = (python -c "import os, sys; print(os.path.dirname(sys.executable))")
$env:Path += ";$PYTHON_PATH"

Now, build the documentation:

make clean html --directory=docs

cd docs
make.bat clean html

The main page of the documentation can be found in /docs/build/html/index.html.