Sphinx use

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 <jules_docs>`                  |
-+----------------------------+-----------------------------+-------------------------------------------------+
-| 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
-<https://code.metoffice.gov.uk/trac/lfric/wiki/LFRicTechnical/Documentation/DoxygenUsage>`__.
+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
+<https://metoffice.github.io/lfric_core/how_to_contribute/style_guides/doxygen_style_guide.html>`_.
 
 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.
+

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
+<sphinx>`. 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 <path_to>/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

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 <https://www.sphinx-doc.org/en/master/>`_ 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
+        <https://metoffice.github.io/lfric_core/how_to_contribute/style_guides
+        /documentation_style_guide.html>`_ 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