Creating the HTML Basilisk Documentation using Sphinx/Doxygen

Documentation Description

The Sphinx and Doxygen software packages provide an elegant method to both include code explanations, definitions and module documentation, but also to create a full HTML based documentation folder for a software project. An online copy of this HTML documentation is hosted at AVS Basilisk web site with the Documentation page.

Tool Requirements

You need to have command line versions of Doxygen and Graphviz installed on your system. The Doxygen download page contains a range of pre-compiled binaries for many different platforms. Graphviz provides the dot executable used by Sphinx to render module I/O diagrams.

On macOS the Homebrew tool is also a very convenient method to install these tools by typing in the terminal:

brew install doxygen graphviz

On Ubuntu or Debian Linux systems these tools can be installed with:

sudo apt install doxygen graphviz

If you are using a conda environment, Graphviz can also be installed with:

conda install conda-forge::graphviz

You can verify that Graphviz is available with:

dot -V

To install the required python packages run the command:

pip install -r requirements_doc.txt

Making the HTML Documentation Folder

First generate the test plots:

cd src

pytest -n auto

Next, in a terminal window switch to the docs folder:

cd docs

Finally, type the following command to build the HTML documentation:

make html

The final html documenation folder is stored in docs/build/html.

To open the HTML index file and view the documentation in the browser use:

make view

To clean out the sphinx generated documents and folder use:

make clean