...

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. Unlike compiling and running the model, the documentation can be easily built and displayed on your laptop. Here is one way to do that.

Create a local python virtual environment for the doc building packages (one time setup)

On your local laptop in your home directory, create a python virtual environment called “mkdocsenv”

python3 -m venv mkdocsenv (you can call it something else besides “mkdocsenv”)

Now enter that environment with

source mkdocsenv/bin/activate

Install the python packages needed:

pip install mkdocs-material

...

The creation of mkdocsenv and the pip install commands only has have to be done once on each platform you want to do documentation development.

...

cd top the top level E3SM directory and see if you can build the current docs by typing

mkdocs buildRepeat 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

(Follow the instructions output by the above command to display in your browser. control-C to end server)

As you edit the documentation, rerun the “mkdocs build” command and refresh the website in your browser. The output of “mkdocs build” will tell you if you have a syntax error in your markdown files. The website in your browser will let you know if it looks as you intended

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.

...