Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Expand
titleAlternative method: Using conda

The same python environment above can be achieve achieved with conda. To do so, create a conda environment with a conda create -n e3sm_docs mkdocs-material pymdown-extensions mkdocs-monorepo-plugin mdutils mkdocs-bibtex then conda activate e3sm_docs to use the environment.

...

source mkdocsenv/bin/activate

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

...

Expand
titleA note on EAMxx docs

EAMxx docs use an automated routine to populate the namelist parameters. In order to avoid warnings on this step, please ensure you have a copy of the CIME submodule inside your main repo. Proceed to executing eamxx-params-docs-autogen in the components/eamxx/scripts directory. Then, you will be able to build with mkdocs build --strict --verbose (to convert any warning into an error, which we use in the PR checking).

...

Keep figures in the same directory as the Markdown file referencing them.

Markdown style guide

To help with maintainability, everyone is encouraged to follow best practices when it comes to writing markdown files. For example, popular IDEs support markdownlint (https://github.com/DavidAnson/markdownlint)

Automated preview during PRs

When you submit a PR, we have an automated process to build and test the docs (with --strict --verbose) and to preview them directly in the PR. An automated bot will leave a comment with a URL for you to review the docs.