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..4f4839b2 --- /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 a + useful resource. + + +Building the documentation +-------------------------- + +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