Adding Alastair's how-to to RTD

Author: Will Benfold

docs/src/developers_guide/contributing_documentation.rst

@@ -1,173 +1,21 @@
 
-.. _contributing.documentation:
-
 Contributing to the Documentation
 ---------------------------------
 
 Documentation is important and we encourage any improvements that can be made.
 If you believe the documentation is not clear please contribute a change to
 improve the documentation for all users.
 
-Any change to the Iris project whether it is a bugfix, new feature or
-documentation update must use the :ref:`development-workflow`.
-
-
-Requirements
-~~~~~~~~~~~~
-
-The documentation uses specific packages that need to be present.  Please see
-:ref:`installing_iris` for instructions.
-
-
-.. _contributing.documentation.building:
-
-Building
-~~~~~~~~
-
-This documentation was built using the latest Python version that Iris
-supports.  For more information see :ref:`installing_iris`.
-
-The build can be run from the documentation directory ``docs/src``.
-
-The build output for the html is found in the ``_build/html`` sub directory.
-When updating the documentation ensure the html build has *no errors* or
-*warnings* otherwise it may fail the automated `cirrus-ci`_  build.
-
-Once the build is complete, if it is rerun it will only rebuild the impacted
-build artefacts so should take less time.
-
-There is an option to perform a build but skip the
-:ref:`contributing.documentation.gallery` creation completely.  This can be
-achieved via::
-
-    make html-noplot
-
-Another option is to skip the :ref:`iris` documentation creation.  This can be
-useful as it reduces the time to build the documentation, however you may have
-some build warnings as there maybe references to the API documentation.
-This can be achieved via::
-
-    make html-noapi
-
-You can combine both the above and skip the
-:ref:`contributing.documentation.gallery` and :ref:`iris` documentation
-completely.  This can be achieved via::
-
-    make html-quick
-
-If you wish to run a full clean build you can run::
-
-    make clean
-    make html
-
-This is useful for a final test before committing your changes.
-
-.. note:: In order to preserve a clean build for the html, all **warnings**
-          have been promoted to be **errors** to ensure they are addressed.
-          This **only** applies when ``make html`` is run.
-
-.. _cirrus-ci: https://cirrus-ci.com/github/SciTools/iris
-
-.. _contributing.documentation.testing:
-
-Testing
-~~~~~~~
-
-There are a ways to test various aspects of the documentation.  The
-``make`` commands shown below can be run in the ``docs`` or
-``docs/src`` directory.
-
-Each :ref:`contributing.documentation.gallery` entry has a corresponding test.
-To run the tests::
-
-    make gallerytest
-
-Many documentation pages includes python code itself that can be run to ensure
-it is still valid or to demonstrate examples.  To ensure these tests pass
-run::
-
-    make doctest
-
-See :data:`iris.cube.Cube.data` for an example of using the `doctest`_
-approach.
-
-.. _doctest: http://www.sphinx-doc.org/en/stable/ext/doctest.html
-
-The hyperlinks in the documentation can be checked automatically.
-If there is a link that is known to work it can be excluded from the checks by
-adding it to the ``linkcheck_ignore`` array that is defined in the
-`conf.py`_.  The hyperlink check can be run via::
-
-    make linkcheck
-
-If this fails check the output for the text **broken** and then correct
-or ignore the url.
-
-.. comment
-    Finally, the spelling in the documentation can be checked automatically via the
-    command::
-
-        make spelling
-
-    The spelling check may pull up many technical abbreviations and acronyms.  This
-    can be managed by using an **allow** list in the form of a file.  This file,
-    or list of files is set in the `conf.py`_ using the string list
-    ``spelling_word_list_filename``.
-
-
-.. note:: In addition to the automated `cirrus-ci`_ build of all the
-          documentation build options above, the
-          https://readthedocs.org/ service is also used.  The configuration
-          of this held in a file in the root of the
-          `github Iris project <https://github.com/SciTools/iris>`_  named
-          ``.readthedocs.yml``.
-
-
-.. _conf.py: https://github.com/SciTools/iris/blob/main/docs/src/conf.py
-
-
-.. _contributing.documentation.api:
-
-Generating API Documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In order to auto generate the API documentation based upon the docstrings a
-custom set of python scripts are used, these are located in the directory
-``docs/src/sphinxext``.  Once the ``make html`` command has been run,
-the output of these scripts can be found in
-``docs/src/generated/api``.
-
-If there is a particularly troublesome module that breaks the ``make html`` you
-can exclude the module from the API documentation.  Add the entry to the
-``exclude_modules`` tuple list in the
-``docs/src/sphinxext/generate_package_rst.py`` file.
-
-
-.. _contributing.documentation.gallery:
-
-Gallery
-~~~~~~~
-
-The Iris :ref:`sphx_glr_generated_gallery` uses a sphinx extension named
-`sphinx-gallery <https://sphinx-gallery.github.io/stable/>`_
-that auto generates reStructuredText (rst) files based upon a gallery source
-directory that abides directory and filename convention.
-
-The code for the gallery entries are in ``docs/gallery_code``.
-Each sub directory in this directory is a sub section of the gallery.  The
-respective ``README.rst`` in each folder is included in the gallery output.
-
-For each gallery entry there must be a corresponding test script located in
-``docs/gallery_tests``.
+If you're confident diving right in, please head for
+:ref:`contributing.documentation`.
 
-To add an entry to the gallery simple place your python code into the
-appropriate sub directory and name it with a prefix of ``plot_``.  If your
-gallery entry does not fit into any existing sub directories then create a new
-directory and place it in there.
+If you're not then we've got a step-by-step guide here to walk you through it:
+:ref:`contributing.documentation_easy`
 
-The reStructuredText (rst) output of the gallery is located in
-``docs/src/generated/gallery``.
+.. toctree::
+   :maxdepth: 1
+   :hidden:
 
-For more information on the directory structure and options please see the
-`sphinx-gallery getting started
-<https://sphinx-gallery.github.io/stable/getting_started.html>`_ documentation.
+   contributing_documentation_easy
+   contributing_documentation_full
+   

docs/src/developers_guide/contributing_documentation_easy.rst

@@ -0,0 +1,95 @@
+
+.. _contributing.documentation_easy:
+
+Contributing to the Documentation (the easy way)
+------------------------------------------------
+
+Documentation is important and we encourage any improvements that can be made.
+If you believe the documentation is not clear please contribute a change to
+improve the documentation for all users.
+
+The guide below is designed to be accessible to those with little-to-no
+knowledge of programming and GitHub. If you find that something doesn't work as
+described or could use more explanation then please let us know (or contribute
+the improvement yourself)!
+
+First time only steps
+^^^^^^^^^^^^^^^^^^^^^
+ 
+1. Create a `GitHub <https://github.com/>`_ account.
+
+2. Complete the Scitools Contributor License Agreement (`link to Google Form
+   <https://docs.google.com/forms/d/e/1FAIpQLSfd0tdE-DcJOXh8ej_7T93IizwJFYBFyRWYQOi2A8QRaKwykA/viewform>`_).
+   This is a one-off requirement for anyone who wishes to contribute to a
+   Scitools repository - including the documentation.
+
+Steps to complete each time you propose changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. Navigate to documentation page that you want to edit (on this site).
+
+2. Click the 'Edit on GitHub' button at the top right of the page.
+
+.. image:: edit_on_github.png
+
+3. In the resulting GitHub page select **main** from the drop-down menu near
+   the top left of the page (to the left of the 'iris / docs / src / …' links)
+   if it isn't already. This changes the branch to main.
+
+.. image:: find_main.png
+
+4. Click the pencil symbol near the top right (to the right of the 'Raw' and
+   'Blame' buttons).
+
+.. image:: edit_button.png
+
+5. Make your edits! Try to strike a balance between informing the audience
+   enough that they understand and overwhelming them with information.
+
+.. note::
+
+    You may see the following message at the top of the edit page, informing you
+    that GitHub has created you your own 'fork' (or copy) of the project as a
+    precursor to allowing you to edit the page. Your changes will be merged into
+    the main version of the documentation later.
+
+    .. image:: fork_banner.png
+
+6. Scroll to the bottom of the edit page and enter some appropriate information
+   in the two boxes under 'Propose changes'. You can just keep the default text
+   if you like or enter something more specific - a short sentence explaining
+   what's changed is fine. Then click the 'Propose changes' button.
+
+.. image:: propose_changes.png
+
+7. In the resulting page titled 'Pull Request', write a brief description of
+   what you've changed underneath the following three lines:
+
+.. code::
+
+    ### Description
+    <!-- Provide a clear description about your awesome pull request -->
+    <!-- Tell us all about your new feature, improvement, or bug fix -->
+
+Describing what you've changed and why will help the person who reviews your changes.
+
+.. image:: pull_request.png
+
+8.	Click the 'Create pull request' button.
+
+What happens next?
+^^^^^^^^^^^^^^^^^^
+
+Someone else who works on Iris will review your changes (this happens for
+everyone who makes changes to Iris or its documentation). The reviewer might
+make comments or ask questions (don't worry about missing these, GitHub will
+email you to let you know). You can respond to these comments underneath where
+they appear in GitHub.
+
+Once you've worked everything out together, the reviewer will merge your changes
+into the main version of the documentation so that they're accessible for
+everyone to benefit from.
+
+**You've now contributed to the Iris documentation!** If you've caught the bug
+and want to get more involved (or you're just interested what that would mean)
+then chat to the person reviewing your code or another Iris developer.