================================================================= 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 .. code-block:: bash $ 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 .. code-block:: bash $ 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 .. code-block:: bash $ 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| image:: browserroot.png :scale: 70 % |browserroot| And, we can copy the tarzipped file to a webserver and deploy it in an appropriate location for access. .. toctree::