From 3dffa6d053b6ed850f97d19a5b7eacd41993b6ad Mon Sep 17 00:00:00 2001 From: Bill Little Date: Tue, 28 Jan 2025 01:14:38 +0000 Subject: [PATCH 1/3] docs: initial developer documentation guildlines --- .../_static/images/icons/documentation.svg | 1 + docs/src/common.txt | 12 ++ docs/src/developer/documentation.rst | 129 ++++++++++++++++++ docs/src/developer/index.rst | 14 +- docs/src/reference/glossary.rst | 5 + docs/src/reference/index.rst | 2 +- 6 files changed, 161 insertions(+), 2 deletions(-) create mode 100644 docs/src/_static/images/icons/documentation.svg create mode 100644 docs/src/developer/documentation.rst diff --git a/docs/src/_static/images/icons/documentation.svg b/docs/src/_static/images/icons/documentation.svg new file mode 100644 index 00000000..ad707817 --- /dev/null +++ b/docs/src/_static/images/icons/documentation.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/src/common.txt b/docs/src/common.txt index 09b3c2d8..b0b5dd71 100644 --- a/docs/src/common.txt +++ b/docs/src/common.txt @@ -5,9 +5,11 @@ .. _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 +.. _Jupyter: https://jupyter.org/ .. _Kitware: https://www.kitware.com/ .. _Matplotlib: https://github.com/matplotlib/matplotlib .. _Natural Earth Features: https://www.naturalearthdata.com/features/ @@ -30,16 +32,26 @@ .. _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 +.. _make: https://www.gnu.org/software/make/ .. _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 diff --git a/docs/src/developer/documentation.rst b/docs/src/developer/documentation.rst new file mode 100644 index 00000000..fe0efeb5 --- /dev/null +++ b/docs/src/developer/documentation.rst @@ -0,0 +1,129 @@ +.. 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 to view the rendered documentation. This is | + | | necessary to in order to support the 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: + + +.. _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 diff --git a/docs/src/developer/index.rst b/docs/src/developer/index.rst index 92b9e7ce..0a34497d 100644 --- a/docs/src/developer/index.rst +++ b/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 diff --git a/docs/src/reference/glossary.rst b/docs/src/reference/glossary.rst index 75fe5328..ba996004 100644 --- a/docs/src/reference/glossary.rst +++ b/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`. diff --git a/docs/src/reference/index.rst b/docs/src/reference/index.rst index 60f1bc5f..926cbe0a 100644 --- a/docs/src/reference/index.rst +++ b/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 From decc1a5c0af11e3e955c94ef0e28027e40f4f66d Mon Sep 17 00:00:00 2001 From: Bill Little Date: Tue, 28 Jan 2025 08:13:20 +0000 Subject: [PATCH 2/3] add changelog news fragment --- changelog/1298.contributor.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/1298.contributor.rst diff --git a/changelog/1298.contributor.rst b/changelog/1298.contributor.rst new file mode 100644 index 00000000..e0029f62 --- /dev/null +++ b/changelog/1298.contributor.rst @@ -0,0 +1 @@ +Added :ref:`gv-developer-documentation` guidelines. (:user:`bjlittle`) From 052792dcb524963e809926bc18e2249caf482812 Mon Sep 17 00:00:00 2001 From: Bill Little Date: Tue, 28 Jan 2025 08:13:20 +0000 Subject: [PATCH 3/3] add changelog news fragment --- docs/src/common.txt | 2 -- docs/src/conf.py | 1 + docs/src/developer/documentation.rst | 18 ++++++++++-------- 3 files changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/src/common.txt b/docs/src/common.txt index b0b5dd71..7a882ed5 100644 --- a/docs/src/common.txt +++ b/docs/src/common.txt @@ -9,7 +9,6 @@ .. _GeoVista: https://github.com/bjlittle/geovista .. _Issue: https://github.com/bjlittle/geovista/issues .. _Issues: https://github.com/bjlittle/geovista/issues -.. _Jupyter: https://jupyter.org/ .. _Kitware: https://www.kitware.com/ .. _Matplotlib: https://github.com/matplotlib/matplotlib .. _Natural Earth Features: https://www.naturalearthdata.com/features/ @@ -39,7 +38,6 @@ .. _geovista-data: https://github.com/bjlittle/geovista-data .. _geovista-media: https://github.com/bjlittle/geovista-media .. _iris: https://github.com/scitools/iris -.. _make: https://www.gnu.org/software/make/ .. _matplotlib: https://github.com/matplotlib/matplotlib .. _myst-nb: https://github.com/executablebooks/MyST-NB .. _myst-parser: https://github.com/executablebooks/MyST-Parser diff --git a/docs/src/conf.py b/docs/src/conf.py index 2b1aee6f..ca157801 100644 --- a/docs/src/conf.py +++ b/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 diff --git a/docs/src/developer/documentation.rst b/docs/src/developer/documentation.rst index fe0efeb5..a33d3cd7 100644 --- a/docs/src/developer/documentation.rst +++ b/docs/src/developer/documentation.rst @@ -17,14 +17,14 @@ The documentation is built using `sphinx`_ to parse and render `reStructuredText 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. +`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. +The documentation is built using `sphinx-build`_ and the `GNU make`_ tool. :fa:`pump-medical` Hygiene @@ -93,12 +93,12 @@ How-to serve the rendered documentation for inspection in a local browser. :widths: 1 3 :align: center - +------------------------+----------------------------------------------------------------------------------+ - | Make Command | Description | - +========================+==================================================================================+ - | :guilabel:`serve-html` | Start a local ``HTTP`` server to view the rendered documentation. This is | - | | necessary to in order to support the interactive scenes. | - +------------------------+----------------------------------------------------------------------------------+ + +------------------------+-------------------------------------------------------------------------------------+ + | 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 @@ -125,5 +125,7 @@ Perform documentation quality assurance. 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