Versions Compared

Old Version 10

changes.mady.by.user Robert Jacob

Saved on

compared with

New Version 11

changes.mady.by.user Naser Mahfouz

Saved on

Key

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

...

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.

Expand
titleAlternative method: Using conda

The same python environment above can be achieve 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.

Use local environment to build/test documentation changes

...

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

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. 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).

Expand
titleAn alternative to mkdocs serve

An alternative to mkdocs serve is to access to the docs directly without serving them through a URL. To achieve this, one could you file:///E3SM_ROOT/site/index.html in a modern browser like Chrome (in place of a URL). In this case, E3SM_ROOT is the full path to the clone E3SM repository on your local machine. One could directly go to other pages as needed using the same method (e.g., file:///E3SM_ROOT/site/EAM/index.html).

Documentation organization

...