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 a command line version of Doxygen installed on your system. The Doxygen download page contains a range of pre-compiled binaries for many different platforms.

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

brew install doxygen

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 documenation:

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