How to Build the Documentation

Last Updated: January 2025

This section will guide you through the process of building the Tethys Platform documentation on your local machine.

Install Prerequisites

Before building the documentation, you will need to install the following prerequisites:
- Miniconda - Python package manager
- Git - Version control system
- Git LFS - Git extension for managing image and binary files
Clone the Repository

Clone your fork of the Tethys Platform GitHub repository to your local machine (see: Development Process):
```
git clone <FORK_URL>
```
Initialize Git LFS and Pull Images Initialize Git LFS in the repository and pull the images:
```
git lfs install
git lfs pull
```
Note

Once Git LFS is installed in your repository, you can commit new images to the repository in the normal fashion. Git LFS will automatically manage the storage of the images.
Create the Docs Environment

Create the conda environment for building the documentation:
```
conda env create -f docs/docs_environment.yml
```
Then activate the environment:
```
conda activate tethys-docs
```
Build the Documentation

Build the documentation using the Makefile:
```
make html
```
The built documentation will be located in the docs/_build/html directory.
View the Documentation

Open the built documentation in your web browser. Locate the index.html file in the docs/_build/html directory and open it in your preferred browser.

sphinx-autobuild

Any time you make changes to the documentation source files, you will need to rebuild the documentation to see the changes. To avoid having to manually rebuild the documentation every time you make a change, you can use the sphinx-autobuild tool. It watches the source files for changes and automatically rebuilds the documentation and reloads the browser when changes are detected.

To use sphinx-autobuild, run the following commands:

cd docs
sphinx-autobuild --host 127.0.0.1 --port 8001 . ./_build/html

Cleaning the Build Directory

Occasionally, you'll want to clean the build directory to rebuild the documentation from scratch. To do this, run the following command:

make clean

If the documentation doesn't open in your web browser automatically, navigate to http://127.0.0.1:8001 in your browser to view the documentation. The documentation will automatically rebuild and reload in the browser when changes are detected.

Contributing Documentation

Documentation Guidelines