From 49a580ee77d9c5e761938c0e7822af3076c8bcf7 Mon Sep 17 00:00:00 2001 From: jennyhickson Date: Fri, 17 Oct 2025 11:11:48 +0100 Subject: [PATCH 1/4] reorganise the documentation --- source/Development/documentation.rst | 59 +++++++++++++-------- source/Development/jules_docs.rst | 63 +++------------------- source/Development/sphinx_docs.rst | 78 ++++++++++++++++++++++++++++ 3 files changed, 122 insertions(+), 78 deletions(-) create mode 100644 source/Development/sphinx_docs.rst diff --git a/source/Development/documentation.rst b/source/Development/documentation.rst index 1257bd8d..3055116a 100644 --- a/source/Development/documentation.rst +++ b/source/Development/documentation.rst @@ -1,47 +1,60 @@ .. _docs: Documentation -------------- +============= All projects have their own scientific and technical documentation. Most notably: -+----------------------------+-----------------------------+-------------------------------------------------+ -| UM Documentation Papers |`view UM`_ | `edit UM`_ | -+----------------------------+-----------------------------+-------------------------------------------------+ -| JULES User Guide |`view JULES`_ | :doc:`edit JULES ` | -+----------------------------+-----------------------------+-------------------------------------------------+ -| LFRic Documentation Papers |`view LFRic`_ | `edit LFRIc`_ | -+----------------------------+-----------------------------+-------------------------------------------------+ ++----------------------------+-----------------------------+ +| UM Documentation Papers |`view UM`_ | ++----------------------------+-----------------------------+ +| JULES User Guide |`view JULES`_ | ++----------------------------+-----------------------------+ +| LFRic Core |`view LFRic Core`_ | ++----------------------------+-----------------------------+ +| LFRic Apps |`view LFRic Apps`_ | ++----------------------------+-----------------------------+ +.. _view UM: https://code.metoffice.gov.uk/doc/um/latest/umdp.html +.. _view JULES: https://jules-lsm.github.io/latest/index.html +.. _view LFRic Core: https://metoffice.github.io/lfric_core/ +.. _view LFRic Apps: https://metoffice.github.io/lfric_apps/ -LFRic Apps and Core also use doxygen to document the code and all changes -should include appropriate doxygen changes to go with them. Doxygen guidelines -are available on the `LFRic Technical pages -`__. +Increasingly this documentation is stored as restructuredText markdown files +alongside the code. This is then compiled using Sphinx into the webpages above. .. toctree:: - :hidden: + :maxdepth: 1 + sphinx_docs jules_docs -.. _view UM: https://code.metoffice.gov.uk/doc/um/latest/umdp.html -.. _edit UM: https://code.metoffice.gov.uk/trac/um/wiki/WorkingPractices/Documentation/UpdatingUMDPs -.. _view JULES: https://jules-lsm.github.io/latest/index.html -.. _edit JULES: https://code.metoffice.gov.uk/trac/jules/wiki/BuildingEditingUserGuide -.. _view LFRic: https://code.metoffice.gov.uk/trac/lfric/wiki/LFRicDocumentationPapers -.. _edit LFRIc: https://code.metoffice.gov.uk/trac/lfric/wiki/LFRicTechnical#Documentation +.. admonition:: + update with relevant UM details. Add a page to the toctree above? + + The UM documentation papers are written in LaTeX and stored in a separate + repository. Guidelines for editing the UM documentation papers are available + here `https://code.metoffice.gov.uk/trac/um/wiki/WorkingPractices/Documentation + /UpdatingUMDPs`_. + +LFRic Apps and Core also use doxygen to document the code and all changes +should include appropriate doxygen changes to go with them. Doxygen guidelines +are available in the `LFRic Core Documentation +`_. Small changes and bug fixes rarely need documentation to be updated, but when new science is added to a project, the documentation must be updated to ensure that it remains contemporary with the code. +Documentation changes that are held within a repository should be documented +with issues and pull requests, are formally reviewed, and should be included +on the same branch as the code changes. Apply the `Documentation` label to your +pull request. + .. tip:: Searching the relevant documentation for words related to your change is often useful when deciding whether to update the documentation. -Documentation changes that are held within a repository are formally reviewed, -and should be included on the same ticket as the code changes - making sure -both code and docs branches are clearly listed and the `doc` keyword is -applied. + diff --git a/source/Development/jules_docs.rst b/source/Development/jules_docs.rst index 1554730b..1625fa57 100644 --- a/source/Development/jules_docs.rst +++ b/source/Development/jules_docs.rst @@ -1,66 +1,19 @@ .. _jules_docs: -Building and editing the JULES User Guide -========================================= - -The JULES User Guide is built using the Sphinx Documentation Generator. The -documentation is written in plain text files using a markup language called -reStructuredText. The source files for the JULES documentation are contained -in the `JULES GitHub repository`_. The plain text files are contained in the -`source`_ directory and have the extension ``.rst``. Sphinx can take these -plain text files and generate both HTML and PDF documentation from them -(complete with cross-referencing links, etc.). Since reStructuredText is a -plain text format, your favourite text editor is all you need to edit the -JULES documentation. +The JULES User Guide +==================== + +The JULES User Guide is built using the :ref:`Sphinx Documentation Generator +`. The source files for the JULES documentation are contained +in the `JULES GitHub repository`_, with the plain text files contained in the +`source`_ directory. .. _JULES GitHub repository: https://github.com/jules-lsm/jules-lsm.github.io .. _source: https://github.com/jules-lsm/jules-lsm.github.io/tree/master/user_guide/doc/source The JULES User Guide uses some custom extensions to reStructuredText to allow it to represent Fortran namelists more effectively - these are discussed in -more detail below. Other than that, the `Sphinx documentation`_ is an -excellent resource. - -.. _Sphinx documentation: https://www.sphinx-doc.org/en/master/ - - -Building the JULES User Guide ------------------------------ - -For first time users, please create the production environment to build the -documentation. From the top level of the repository run: - -.. code-block:: shell - - conda env create -f environment.yml - -Activate the environment: - -.. code-block:: shell - - conda activate jules-user-guide - -Move to the correct directory: - -.. code-block:: shell - - cd /jules-user-guide-test/doc - -Run ``make`` to build the documentation: - -To build and view the HTML documentation: - -.. code-block:: shell - - make html - firefox build/html/index.html - -To build and view the PDF documentation: - -.. code-block:: shell - - make latexpdf - evince build/latex/JULES_User_Guide.pdf +more detail below. reStructuredText Extension for Fortran Namelists diff --git a/source/Development/sphinx_docs.rst b/source/Development/sphinx_docs.rst new file mode 100644 index 00000000..bb2d3885 --- /dev/null +++ b/source/Development/sphinx_docs.rst @@ -0,0 +1,78 @@ +.. _sphinx: + +Sphinx Documentation +==================== +The documentation is written in plain text files using a markup language called +reStructuredText. The text files have the extension ``.rst``. Sphinx can +take these text files and generate both HTML and PDF documentation from them +(complete with cross-referencing links, etc.). Since reStructuredText is a +plain text format, your favourite text editor is all you need to edit the +documentation. + +.. tip:: + The `Sphinx documentation `_ is an + useful resource. + + +Building the JULES User Guide +----------------------------- + +Please create the production environment to build the +documentation (first time users only), and then activate it. + +.. tab-set:: + + .. tab-item:: JULES + + From the top level of the repository: + + .. code-block:: shell + + conda env create -f environment.yml + + Activate the environment: + + .. code-block:: shell + + conda activate jules-user-guide + + .. tab-item:: LFRic Apps and Core + + On the Met Office Azure Spice machine the main LFRic module environment + contains all the required packages to build the documentation. Ensure + this is loaded. + + Note there is a `style guide included in the LFRic Core documentation + `_ that should be followed for both + these repositories. + + .. tab-item:: Working Practices + + From the top level of the repository: + + .. code-block:: shell + + conda env create -f env.yml + + Activate the environment: + + .. code-block:: shell + + conda activate sphinx_doc_env + +Move to the documentation directory and run ``make`` to build the documentation: + +To build and view the HTML documentation: + +.. code-block:: shell + + make [clean] html + firefox build/html/index.html + +To build and view the PDF documentation: + +.. code-block:: shell + + make latexpdf + evince build/latex/JULES_User_Guide.pdf From 8e8942120d4385e52c1a9344ab1e92a87f24a601 Mon Sep 17 00:00:00 2001 From: Jenny Hickson <61183013+jennyhickson@users.noreply.github.com> Date: Fri, 17 Oct 2025 12:03:39 +0100 Subject: [PATCH 2/4] Apply suggestion from @james-bruten-mo Co-authored-by: James Bruten <109733895+james-bruten-mo@users.noreply.github.com> --- source/Development/sphinx_docs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/Development/sphinx_docs.rst b/source/Development/sphinx_docs.rst index bb2d3885..00d7f8c1 100644 --- a/source/Development/sphinx_docs.rst +++ b/source/Development/sphinx_docs.rst @@ -10,7 +10,7 @@ plain text format, your favourite text editor is all you need to edit the documentation. .. tip:: - The `Sphinx documentation `_ is an + The `Sphinx documentation `_ is a useful resource. From 15b78abba269fd839622f02a855b9b114e5d25f9 Mon Sep 17 00:00:00 2001 From: Jenny Hickson <61183013+jennyhickson@users.noreply.github.com> Date: Fri, 17 Oct 2025 12:03:59 +0100 Subject: [PATCH 3/4] Apply suggestion from @james-bruten-mo Co-authored-by: James Bruten <109733895+james-bruten-mo@users.noreply.github.com> --- source/Development/sphinx_docs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/Development/sphinx_docs.rst b/source/Development/sphinx_docs.rst index 00d7f8c1..46a2612c 100644 --- a/source/Development/sphinx_docs.rst +++ b/source/Development/sphinx_docs.rst @@ -68,7 +68,7 @@ To build and view the HTML documentation: .. code-block:: shell make [clean] html - firefox build/html/index.html + firefox build/html/index.html & To build and view the PDF documentation: From 253fe736c735c1760feb439c82856936c05f3c7c Mon Sep 17 00:00:00 2001 From: jennyhickson Date: Fri, 17 Oct 2025 12:05:21 +0100 Subject: [PATCH 4/4] update title --- source/Development/sphinx_docs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/Development/sphinx_docs.rst b/source/Development/sphinx_docs.rst index bb2d3885..f6a42457 100644 --- a/source/Development/sphinx_docs.rst +++ b/source/Development/sphinx_docs.rst @@ -14,8 +14,8 @@ documentation. useful resource. -Building the JULES User Guide ------------------------------ +Building the documentation +-------------------------- Please create the production environment to build the documentation (first time users only), and then activate it.