docs: initial developer documentation guildlines

changelog/1298.contributor.rst

@@ -0,0 +1 @@
+Added :ref:`gv-developer-documentation` guidelines. (:user:`bjlittle`)

docs/src/common.txt

@@ -5,6 +5,7 @@
 .. _Cartopy: https://github.com/SciTools/cartopy
 .. _Diátaxis: https://diataxis.fr/
 .. _Discussions: https://github.com/bjlittle/geovista/discussions
+.. _Executable Books: https://github.com/executablebooks
 .. _GeoVista: https://github.com/bjlittle/geovista
 .. _Issue: https://github.com/bjlittle/geovista/issues
 .. _Issues: https://github.com/bjlittle/geovista/issues
@@ -30,16 +31,25 @@
 .. _conda: https://docs.conda.io/projects/conda/en/latest/index.html
 .. _conda environment.yml file: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#creating-an-environment-from-an-environment-yml-file
 .. _conda-forge: https://anaconda.org/conda-forge/geovista
+.. _docutils: https://github.com/docutils/docutils
 .. _feedstock: https://github.com/conda-forge/geovista-feedstock
 .. _geopandas: https://github.com/geopandas/geopandas
 .. _geovista: https://github.com/bjlittle/geovista
 .. _geovista-data: https://github.com/bjlittle/geovista-data
 .. _geovista-media: https://github.com/bjlittle/geovista-media
 .. _iris: https://github.com/scitools/iris
 .. _matplotlib: https://github.com/matplotlib/matplotlib
+.. _myst-nb: https://github.com/executablebooks/MyST-NB
+.. _myst-parser: https://github.com/executablebooks/MyST-Parser
 .. _pip: https://pip.pypa.io/en/stable/index.html
 .. _pre-commit: https://pre-commit.com/
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+.. _sphinx: https://github.com/sphinx-doc/sphinx
+.. _sphinx-autoapi: https://github.com/readthedocs/sphinx-autoapi
+.. _sphinx-build: https://www.sphinx-doc.org/en/master/man/sphinx-build.html
 .. _sphinx-gallery: https://github.com/sphinx-gallery/sphinx-gallery
+.. _sphinx-tags: https://github.com/melissawm/sphinx-tags
+.. _sphinx.ext.doctest: https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html
 .. _tox: https://tox.wiki/en/stable/
 .. _xarray: https://github.com/pydata/xarray
 

docs/src/conf.py

@@ -509,6 +509,7 @@ def autolog(message: str, section: str | None = None, color: str | None = None)
     "https://www.ncei.noaa.gov/products/optimum-interpolation-sst",
     "https://earthexplorer.usgs.gov",
     "https://www.fvcom.org",
+    "https://www.gnu.org/software/make/",
 ]
 linkcheck_retries = 3
 

docs/src/developer/documentation.rst

@@ -0,0 +1,131 @@
+.. include:: ../common.txt
+
+.. _gv-developer-documentation:
+
+:fa:`square-pen` Documentation
+==============================
+
+Here we provide some high-level guidelines and best practice advice for authors and
+contributors wishing to build and render the documentation.
+
+
+:fa:`screwdriver-wrench` Building
+---------------------------------
+
+The documentation is built using `sphinx`_ to parse and render `reStructuredText`_
+(``rst``) documents into ``HTML``.
+
+We also use `myst-parser`_, a ``sphinx`` and `docutils`_ extension to parse and convert
+:term:`MyST` to ``rst``, and `myst-nb`_ to execute and convert
+`Jupyter Notebooks`_ into ``sphinx`` documents.
+
+.. seealso::
+    :class: margin, dropdown, toggle-shown
+
+    For configuration details see ``Makefile`` and ``conf.py``.
+
+The documentation is built using `sphinx-build`_ and the `GNU make`_ tool.
+
+
+:fa:`pump-medical` Hygiene
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Start afresh by performing documentation hygiene to purge various build artifacts.
+
+.. table:: Housekeeping Commands
+    :widths: 1 3
+    :align: center
+
+    +-------------------------+----------------------------------------------------------------------------------+
+    | Make Command            | Description                                                                      |
+    +=========================+==================================================================================+
+    | :guilabel:`clean`       | Purge all `sphinx-autoapi`_, `sphinx-gallery`_, `sphinx-tags`_, carousel, and    |
+    |                         | other `sphinx-build`_ artifacts.                                                 |
+    +-------------------------+----------------------------------------------------------------------------------+
+    | :guilabel:`clean-all`   | Perform both a ``clean`` and ``clean-cache``.                                    |
+    +-------------------------+----------------------------------------------------------------------------------+
+    | :guilabel:`clean-cache` | Purge the `myst-nb`_ Jupyter cache. See `myst-nb configuration`_                 |
+    |                         | for further details.                                                             |
+    +-------------------------+----------------------------------------------------------------------------------+
+
+
+:fa:`pen-to-square` Build
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Build the documentation along with various controls to limit image creation. Note that building the documentation
+static images and interactive scenes can be resource hungry and time consuming.
+
+.. table:: Build Commands
+    :widths: 2 1 3
+    :align: center
+
+    +----------------------------+---------------------+--------------------------------------------------------------+
+    | Make Command               | Status              | Description                                                  |
+    +============================+=====================+==============================================================+
+    | :guilabel:`html`           | :fas:`square-check` | Build the full suite of documentation including all images   |
+    |                            |                     | and scenes.                                                  |
+    +----------------------------+---------------------+--------------------------------------------------------------+
+    | :guilabel:`html-docstring` | :fas:`square-check` | Build the full suite of documentation and only the           |
+    |                            |                     | ``docstring`` images and scenes.                             |
+    +----------------------------+---------------------+--------------------------------------------------------------+
+    | :guilabel:`html-gallery`   | :fas:`square-check` | Build the full suite of documentation and only the           |
+    |                            |                     | `sphinx-gallery`_ images and scenes, which also includes the |
+    |                            |                     | carousel.                                                    |
+    +----------------------------+---------------------+--------------------------------------------------------------+
+    | :guilabel:`html-inline`    | :fas:`square-xmark` | Build the full suite of documentation and only inline        |
+    |                            |                     | documentation images and scenes. See :far:`circle-dot`       |
+    |                            |                     | :issue:`1150`.                                               |
+    +----------------------------+---------------------+--------------------------------------------------------------+
+    | :guilabel:`html-noplot`    | :fas:`square-check` | Build the full suite of documentation with no static images  |
+    |                            |                     | and no interactive scenes.                                   |
+    +----------------------------+---------------------+--------------------------------------------------------------+
+    | :guilabel:`html-tutorial`  | :fas:`square-check` | Build the full suite of documentation and only the tutorial  |
+    |                            |                     | notebooks.                                                   |
+    +----------------------------+---------------------+--------------------------------------------------------------+
+
+
+:fab:`readme` Render
+~~~~~~~~~~~~~~~~~~~~
+
+How-to serve the rendered documentation for inspection in a local browser.
+
+.. table:: Render Commands
+    :widths: 1 3
+    :align: center
+
+    +------------------------+-------------------------------------------------------------------------------------+
+    | Make Command           | Description                                                                         |
+    +========================+=====================================================================================+
+    | :guilabel:`serve-html` | Start a local ``HTTP`` server on port ``11000`` to view the rendered documentation. |
+    |                        | This is necessary in order to support interactive scenes.                           |
+    +------------------------+-------------------------------------------------------------------------------------+
+
+
+:fa:`vial-circle-check` Test
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Perform documentation quality assurance.
+
+.. table:: Test Commands
+    :widths: 1 3
+    :align: center
+
+    +-----------------------+----------------------------------------------------------------------------------+
+    | Make Command          | Description                                                                      |
+    +=======================+==================================================================================+
+    | :guilabel:`doctest`   | Execute `sphinx.ext.doctest`_ to test snippets within the documentation.         |
+    +-----------------------+----------------------------------------------------------------------------------+
+    | :guilabel:`linkcheck` | Check the integrity of all external links referenced within the documentation    |
+    |                       | using the `sphinx linkcheck builder`_.                                           |
+    +-----------------------+----------------------------------------------------------------------------------+
+
+
+.. comment
+
+    Page link URL resources in alphabetical order:
+
+
+.. _GNU make: https://www.gnu.org/software/make/
+.. _Jupyter Notebooks: https://jupyter.org/
+.. _myst-nb configuration: https://myst-nb.readthedocs.io/en/latest/configuration.html
+.. _sphinx linkcheck builder: https://www.sphinx-doc.org/en/master/usage/builders/index.html#sphinx.builders.linkcheck.CheckExternalLinksBuilder

docs/src/developer/index.rst

@@ -16,7 +16,7 @@
 
 |Contributor Covenant|
 
-Firstly, and most importantly, thank you for contributing! All contributions, no
+Firstly, and most importantly, thanks for contributing! All contributions, no
 matter how large or small are greatly appreciated and welcomed.
 
 Here we provide some guidelines to help get you started on your journey, and
@@ -36,9 +36,21 @@ clarify the various steps involved in how to contribute to ``geovista``.
 
         Towncrier guidelines.
 
+    .. grid-item-card:: Documentation
+        :class-title: custom-title
+        :class-body: custom-body
+        :link: gv-developer-documentation
+        :link-type: ref
+        :img-top: ../_static/images/icons/documentation.svg
+        :class-img-top: dark-light
+        :class-card: sd-rounded-3
+
+        Author & build guidelines.
+
 
 .. toctree::
     :maxdepth: 1
     :hidden:
 
     towncrier
+    documentation

docs/src/reference/glossary.rst

@@ -49,6 +49,11 @@ Say what you mean. Mean what you say.
         A spatially referenced dataset that may be a surface or volume in 3-D
         space. See `What is a Mesh?`_
 
+    MyST
+        *Markedly Structured Text* is a rich and extensible flavour of ``Markdown``
+        for authoring technical and scientific documents. See `myst-nb`_ and
+        `myst-parser`_ from the `Executable Books`_ organisation.
+
     Node
         Nodes are the vertices of a mesh. Also see :term:`Point`.
 

docs/src/reference/index.rst

@@ -28,7 +28,7 @@ Consult our reference material for no fuss facts about ``geovista``.
         :class-img-top: dark-light
         :class-card: sd-rounded-3
 
-        Behaviour and state docstrings.
+        Behaviour & state docstrings.
 
     .. grid-item-card:: Changelog
         :class-title: custom-title