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)
Files and sections
A section of your documentation should be contained entirely in a single file. Short sections can be grouped in to one file.
Equation numbering (and references to equations) will only work within a file.
Figures
When you start adding figures to your documentation, keep in mind that binary files can lead to repo size bloat IF they change a lot so don’t commit a figure to the repo until you are confident its the near-final version.
Figures should be in png format and under 500 pixels on the longest side.
Keep figures in the same directory as the Markdown file referencing them.