...
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.
...
Doing local development of documentation
Just like you compile and test your Fortran before committing it, you need to should “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.
...
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
...
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
Documentation organization
The documentation for a model should be stored within that model’s source code directory.
The first file needed is mkdocs.yml which should be in E3SM/components/<model>. See E3SM/components/eam/mkdocs.yml for an example:
| Code Block | ||
|---|---|---|
| ||
site_name: EAM
nav:
- Introduction: 'index.md'
- Users's Guide: user-guide/index.md
- Developers's Guide: dev-guide/index.md
- Technical Guide: tech-guide/index.md |
The “site_name” is keyword used in the E3SM/docs/index.md file to reference all the model’s documentation. (That file must be edited when adding a new model’s documentation).
All other files should be stored under E3SM/components/<model>/docs
The basic structure under “docs” is
| Code Block | ||
|---|---|---|
| ||
index.md - top level introductory text and links to main sections
dev-guide/ - subdir for development guide
tech-guide/ - subidr for technical guide
user-guide/ - subdir for user guide |
Each of the sub-dirs should also have an “index.md” file to organize their content.
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.
...