About the EHRATM Documentation

The extensive EHRATM documentation is built as a set of five Sphinx projects, all embedded within the high-res-atm repository. The top-level project is located in the repository docs/ subdirectory and includes the introductory and overview material (including this document) to help orient the reader to the project. Then, the other four sphinx projects are located in the docs/ subdirectory of the packages/nwpservice/, packages/ehratm/, packages/ehratmworkflow/ and nwpinstall/ directories. All five projects are structurally independent of each other, by design. We want to be able to restrict the documentation within each package to only that package, as much as possible. This is not entirely possible, of course, since ehratmworkflow depends on ehratm, which depends on nwpservice, but for software management purposes we try to keep the boundaries.

The top-level project, as an overview, does provide links - using the intersphinx extension - to the other four projects. However, there are not links from the four lower-level projects back to the top-level project. I understand it’s a bit awkward, but have felt that implementing this would be problematic

  • If we have any of those four lower-level projects linked to others, they are no longer independent of each other and it can be a real mess to maintain them.

  • Building these “reverse” links, I believe, would be very tedious, making it all even more of a mess to maintain

  • Great care has gone into making sure that this five-project structure can be used to generate a single static HTML file hierarchy that will be portable to any webserver. I fear that this portability would be very difficult to maintain if we added in the reverse links.

Therefore, the only way users can get back to the top-level pages from one of the four lower-level projects is either by repeated “back” clicking, or simply going back to the root URL.

Building the documentation

All of the documentation is versioned within the high-res-atm git repository, and each one of the projects can be built individually. To do so, a number of Python packages are necessary, and this may best be achieved by using the docsenv Conda environment defined in the repository YAML file, misc/conda/docsenv.yml. The installation of the docsenv environment is beyond the scope of this documentation, but is relatively easy to do. Once accomplished, any of the projects can be compiled in their respective docs/ directories

$ conda activate docsenv
$ make html
Running Sphinx v4.0.1
WARNING: html_static_path entry '_static' does not exist
loading pickled environment... done
myst v0.18.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_exten
.
.
.
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in _build/html.

A local web browser can then be pointed to _build/html/index.html for viewing the HTML products.

This approach is very useful for building and modifying single Sphinx projects.

Building the full HTML Documents Tree

It was decided that the entire document system should be built as a single entity in a way that it would be easily exported to any webserver and be readily viewable. The links from top-level document to the four other projects were facilitated through the intersphinx extension. It took a bit of hacking, but with the appropriate and clever use of symbolic links, it was possible to generate the HTML all under a single point. This process was automated through the script misc/utilities/docsbuild.py so that it produces the HTML for each of the five projects, and then arranges it all into a single directory tree, and tarzips it all up so that it can be readily copied to and extracted within any webserver for immediate access.

docsbuild.py only needs to know the path to the high-res-atm directory and, of course, needs to have access to a Python environment such as that provided by the Conda docsenv environment mentioned above. It will ultimately build the entire HTML directory tree in a temporary directory (which means that it can be viewed locally with a web browser) and then tarzip that directory so that it can be copied elsewhere for deployment.

An example of usage

$ conda activate docsenv
$ ~/git/high-res-atm/misc/utilities/docsbuild.py --reporoot /home/morton/git/high-res-atm
All doc dirs found...
Created assembly dir: /tmp/EHRATM_2023-11-25_00_26_47
=================================
Building: docs
Building documents...
Copying /home/morton/git/high-res-atm/docs/_build/html to /tmp/EHRATM_2023-11-25_00_26_47/docs
=================================
=================================
Building: nwpinstall
Building documents...
Copying /home/morton/git/high-res-atm/nwpinstall/docs/_build/html to /tmp/EHRATM_2023-11-25_00_26_47/nwpinstall
=================================
=================================
Building: nwpservice
Running doxygen...
Building documents...
Copying /home/morton/git/high-res-atm/packages/nwpservice/docs/_build/html to /tmp/EHRATM_2023-11-25_00_26_47/nwpservice
=================================
=================================
Building: ehratm
Running doxygen...
Building documents...
Copying /home/morton/git/high-res-atm/packages/ehratm/docs/_build/html to /tmp/EHRATM_2023-11-25_00_26_47/ehratm
=================================
=================================
Building: ehratmworkflow
Building documents...
Copying /home/morton/git/high-res-atm/packages/ehratmworkflow/docs/_build/html to /tmp/EHRATM_2023-11-25_00_26_47/ehratmworkflow
=================================
Copied data available in: /tmp/EHRATM_2023-11-25_00_26_47
Replaced project URLs with web compatible URLs
tarzipped file found at: /tmp/EHRATM_2023-11-25_00_26_47.tgz

The HTML directory tree under /tmp/EHRATM_2023-11-25_00_26_47 looks like

$ tree -L 1 -F /tmp/EHRATM_2023-11-25_00_26_47
/tmp/EHRATM_2023-11-25_00_26_47
├── docs/
├── ehratm/
├── ehratmworkflow/
├── nwpinstall/
└── nwpservice/

and by pointing the web browser to file:///tmp/EHRATM_2023-11-25_00_26_47 we can access the recently compiled document system

browserroot

And, we can copy the tarzipped file to a webserver and deploy it in an appropriate location for access.