Building the Documentation

Follow these steps to build the docs:

# If not already done, clone the project repository.
git clone https://github.com/andthum/mdtools.git
# Enter the docs directory of the project.
cd mdtools/docs/
# Create a virtual Python environment called ".venv-docs".
python3 -m venv .venv-docs
# Activate the virtual Python environment.
source .venv-docs/bin/activate
# Upgrade pip, setuptools and wheel (optional, but recommended).
python3 -m pip install --upgrade pip setuptools wheel
# Install the requirements to build the docs.
python3 -m pip install --upgrade -r requirements-docs.txt
# Enter the root directory of the project.
cd ../
# Install MDTools.
python3 -m pip install --upgrade --editable .

After installing all requirements, the documentation can be built via

# Enter the docs directory of the project.
cd docs/
# Create the documentation.
make html
# Check if the code examples in the documentation work as expected.
make doctest
# Check for broken links.
make linkcheck
# Deactivate the virtual Python environment.
deactivate

Note

Doc pages of scripts might not get updated if you simply run make html after changing a script’s docstring. In this case, you need to re-install MDTools first even if you have installed it in editable mode.

# Enter the root directory of the project.
cd ../
# Install MDTools.
python3 -m pip install --upgrade --editable .
# Enter the docs directory of the project.
cd docs/
# Create the documentation.
make html

Alternatively, you can use from within the docs/ directory:

make install_mdt
make html

To clean the build directory and remove all automatically generated files, run in the docs/ directory the following commands.

make clean
make clean_autosum