The E3SM source code includes the documentation of the model in text files stored along with source code in the main repository.
Like any other new development in the repository, documentation additions should be made on a feature branch and added to the repo with a pull request as described in Development Getting Started Guide .
Our documentation is written in Markdown language. See https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax to get started.
Local development
Just like you compile and test your Fortran before committing it, you need to “compile” and view your documentation before committing and pushing the branch. Here is one way to do that.
Create a local python virtual environment for the doc building packages
On your local laptop in your home directory, create a python virtual environment called “mkdocsenv”
python3 -m venv mkdocsenv
Now enter that environment with
source mkdocsenv/bin/activate
Install the packages needed:
pip install mkdocs-material
pip install mkdocs-monorepo-plugin
Leave the environment by typing
deactivate
The creation of mkdocsenv and pip install commands only has to be done once on each platform you want to do documentation development.
Installing a python package in a virtual environment keeps it from being installed system wide which is good practice and also useful if you don’t have permissions to install system-level packages.
Use local environment to build/test documentation changes.
Activate your virtual environment
source mkdocsenv/bin/activate
cd top the top level E3SM directory and see if you can build the current docs by typing
mkdocs build
Repeat the above command as you make changes to the documentation to make sure you aren’t breaking the documentation build.
You can view the docs locally in your browser with the built-in server
mkdocs serve
(control-C to end server)