diff --git a/docs/gallery_code/README.rst b/docs/gallery_code/README.rst index 02263dc5e5..720fd1e6f6 100644 --- a/docs/gallery_code/README.rst +++ b/docs/gallery_code/README.rst @@ -23,4 +23,4 @@ you may start the jupyter notebook via:: If you wish to contribute to the gallery see the :ref:`contributing.documentation.gallery` section of the -:ref:`contributing.documentation`. +:ref:`contributing.documentation_full`. diff --git a/docs/src/developers_guide/contributing_documentation.rst b/docs/src/developers_guide/contributing_documentation.rst index efd31d4f20..e289b1548d 100644 --- a/docs/src/developers_guide/contributing_documentation.rst +++ b/docs/src/developers_guide/contributing_documentation.rst @@ -1,173 +1,21 @@ -.. _contributing.documentation: - -Contributing to the Documentation ---------------------------------- +How to Contribute 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 `_ 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 `_ -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_full`. -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 -`_ documentation. + contributing_documentation_easy + contributing_documentation_full + \ No newline at end of file diff --git a/docs/src/developers_guide/contributing_documentation_easy.rst b/docs/src/developers_guide/contributing_documentation_easy.rst new file mode 100755 index 0000000000..f54de628bf --- /dev/null +++ b/docs/src/developers_guide/contributing_documentation_easy.rst @@ -0,0 +1,102 @@ + +.. _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 `_ account. + +2. Complete the Scitools Contributor License Agreement (`link to Google Form + `_). + 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 the 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 ``Switch + branches/tags`` 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 + + + +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. + +.. tip:: + + If you're not sure that you're making your pull request right, or have a + question, then make it anyway! You can then comment on it tagging + ``@SciTools/iris-devs`` to ask your question (then edit your pull request if + you need to). + +What Happens Next? +^^^^^^^^^^^^^^^^^^ + +Another Iris contributor 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 contributor. \ No newline at end of file diff --git a/docs/src/developers_guide/contributing_documentation_full.rst b/docs/src/developers_guide/contributing_documentation_full.rst new file mode 100755 index 0000000000..77b898c0f3 --- /dev/null +++ b/docs/src/developers_guide/contributing_documentation_full.rst @@ -0,0 +1,173 @@ + +.. _contributing.documentation_full: + +Contributing to the Documentation +--------------------------------- + +This guide is for those comfortable with the development process, looking for +the specifics of how to apply that knowledge to Iris. You may instead find it +easier to use the :ref:`contributing.documentation_easy`. + +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 `_ 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 `_ +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``. + +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. + +The reStructuredText (rst) output of the gallery is located in +``docs/src/generated/gallery``. + +For more information on the directory structure and options please see the +`sphinx-gallery getting started +`_ documentation. diff --git a/docs/src/developers_guide/edit_button.png b/docs/src/developers_guide/edit_button.png new file mode 100755 index 0000000000..ee2e7858f0 Binary files /dev/null and b/docs/src/developers_guide/edit_button.png differ diff --git a/docs/src/developers_guide/edit_on_github.png b/docs/src/developers_guide/edit_on_github.png new file mode 100755 index 0000000000..f802ebd9d6 Binary files /dev/null and b/docs/src/developers_guide/edit_on_github.png differ diff --git a/docs/src/developers_guide/find_main.png b/docs/src/developers_guide/find_main.png new file mode 100755 index 0000000000..8a7af306cd Binary files /dev/null and b/docs/src/developers_guide/find_main.png differ diff --git a/docs/src/developers_guide/fork_banner.png b/docs/src/developers_guide/fork_banner.png new file mode 100755 index 0000000000..0d140c9fc6 Binary files /dev/null and b/docs/src/developers_guide/fork_banner.png differ diff --git a/docs/src/developers_guide/propose_changes.png b/docs/src/developers_guide/propose_changes.png new file mode 100755 index 0000000000..d4e367ce1d Binary files /dev/null and b/docs/src/developers_guide/propose_changes.png differ diff --git a/docs/src/developers_guide/pull_request.png b/docs/src/developers_guide/pull_request.png new file mode 100755 index 0000000000..bdc0698f54 Binary files /dev/null and b/docs/src/developers_guide/pull_request.png differ diff --git a/docs/src/index.rst b/docs/src/index.rst index 8c3455aba9..e59a6f0527 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -134,7 +134,7 @@ For **Iris 2.4** and earlier documentation please see the .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :caption: Developers Guide :name: development_index :hidden: diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index 62b57e9b29..54fe420729 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -203,6 +203,10 @@ This document explains the changes made to Iris for this release #. `@bjlittle`_ migrated readthedocs to use mambaforge for `faster documentation building`_. (:pull:`4476`) +#. `@wjbenfold`_ contributed `@alastair-gemmell`_'s :ref:`step-by-step guide to + contributing to the docs ` to the docs. + (:pull:`4461`) + 💼 Internal ===========