...
Just like you compile and test your Fortran before committing it, you 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 thatBut first you need to install the python programs needed to build the documentation.
Set up documentation development environment.
You only have to do this once and on each machine you wish to use for writing documentation.
...
| Info |
|---|
An alternative to |
As you edit the documentation, mkdocs will rerun the “mkdocs build” command build and refresh the website in your browserbrowser will update as soon as you hit “save” on a markdown file. 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.
...
tunnel a port to chrysalis from your local machine (e.g.,
ssh -L 12345:localhost:12345 username@chrysalis.lcrc.anl.gov)use e3sm-unified (e.g.,
source /lcrc/soft/climate/e3sm-unified/load_latest_e3sm_unified_chrysalis.sh)develop the docs in your preferred editor
(optionally, starting in e3sm_unified 1.10.0, use the linter, e.g.,
markdownlint-cli2 <my_md_files>)starting in 1.9.3, use mkdocs serve with that port (e.g.,
mkdocs serve -a localhost:12345)then, open the link it prints in your local browser (e.g.,
localhost:12345)(note that you can continue editing and your edits should appear live in the browser window very shortly after making the edits)
...