SciTools · bjlittle · Aug 15, 2020 · Aug 10, 2020 · Aug 11, 2020 · Aug 15, 2020
diff --git a/.travis.yml b/.travis.yml
@@ -21,6 +21,9 @@ env:
     - PYTHON_VERSION=3.7 TEST_TARGET=gallery
     - PYTHON_VERSION=3.7 TEST_TARGET=doctest PUSH_BUILT_DOCS=true
     - PYTHON_VERSION=3.7 TEST_TARGET=linkcheck
+    # TODO: Dependencies for sphinxcontrib-spelling to be in place before this
+    #       spelling code block is enabled
+    #- PYTHON_VERSION=3.7 TEST_TARGET=spelling
 
 git:
   # We need a deep clone so that we can compute the age of the files using their git history.
@@ -144,6 +147,20 @@ script:
       make clean && make linkcheck;
     fi
 
+  # TODO: Dependencies for sphinxcontrib-spelling to be in place before this
+  #       spelling code block is enabled
+
+  # check the spelling in the docs
+  # - >
+  #   if [[ "${TEST_TARGET}" == 'spelling' ]]; then
+  #     MPL_RC_DIR="${HOME}/.config/matplotlib";
+  #     mkdir -p ${MPL_RC_DIR};
+  #     echo 'backend : agg' > ${MPL_RC_DIR}/matplotlibrc;
+  #     echo 'image.cmap : viridis' >> ${MPL_RC_DIR}/matplotlibrc;
+  #     cd ${INSTALL_DIR}/docs/iris;
+  #     make clean && make spelling;
+  #   fi
+
   # Split the organisation out of the slug. See https://stackoverflow.com/a/5257398/741316 for description.
   # NOTE: a *separate* "export" command appears to be necessary here : A command of the
   #   form "export ORG=.." failed to define ORG for the following command (?!)

diff --git a/docs/iris/Makefile b/docs/iris/Makefile
@@ -10,6 +10,11 @@ html-noplot:
         echo "make html-noplot in $$i..."; \
         (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) html-noplot); done
 
+spelling:
+	@for i in $(SUBDIRS); do \
+        echo "make spelling in $$i..."; \
+        (cd $$i; $(MAKE) $(MFLAGS) $(MYMAKEFLAGS) spelling); done
+
 all:
 	@for i in $(SUBDIRS); do \
 		echo "make all in $$i..."; \

diff --git a/docs/iris/gallery_code/README.rst b/docs/iris/gallery_code/README.rst
@@ -7,7 +7,7 @@ to download the code directly as source or as part of a
 `jupyter notebook <https://jupyterlab.readthedocs.io/en/stable/>`_, 
 these links are at the bottom of the page.
 
-In order to successfuly view the jupyter notebook locally so you may
+In order to successfully view the jupyter notebook locally so you may
 experiment with the code you will need an environment setup with the 
 appropriate dependencies, see :ref:`installing_iris` for instructions.  
 Ensure that ``iris-sample-data`` is installed as it is used in the gallery.  

diff --git a/docs/iris/src/Makefile b/docs/iris/src/Makefile
@@ -48,6 +48,11 @@ html-noplot:
 	@echo
 	@echo "Build finished. The HTML (no gallery) pages are in $(BUILDDIR)/html"
 
+spelling:
+	$(SPHINXBUILD) -b spelling $(SRCDIR) $(BUILDDIR)
+	@echo
+	@echo "Build finished. The HTML (no gallery) pages are in $(BUILDDIR)/html"
+
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo

diff --git a/docs/iris/src/conf.py b/docs/iris/src/conf.py
@@ -114,6 +114,8 @@ def autolog(message):
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
+    # TODO: Spelling extension disabled until the dependencies can be included
+    # "sphinxcontrib.spelling",
     "sphinx_gallery.gen_gallery",
     "matplotlib.sphinxext.mathmpl",
     "matplotlib.sphinxext.plot_directive",
@@ -123,10 +125,22 @@ def autolog(message):
     "generate_package_rst",
 ]
 
-# sphinx_copybutton config
+# -- spellingextension --------------------------------------------------------
+# See https://sphinxcontrib-spelling.readthedocs.io/en/latest/customize.html
+spelling_lang = "en_GB"
+# The lines in this file must only use line feeds (no carriage returns).
+spelling_word_list_filename = ["spelling_allow.txt"]
+spelling_show_suggestions = False
+spelling_show_whole_line = False
+spelling_ignore_importable_modules = True
+spelling_ignore_python_builtins = True
+
+# -- copybutton extension -----------------------------------------------------
+# See https://sphinx-copybutton.readthedocs.io/en/latest/
 copybutton_prompt_text = ">>> "
 
 # sphinx.ext.todo configuration
+# See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html
 todo_include_todos = True
 
 # api generation configuration
@@ -141,6 +155,8 @@ def autolog(message):
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+# -- intersphinx extension ----------------------------------------------------
+# See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
 intersphinx_mapping = {
     "cartopy": ("http://scitools.org.uk/cartopy/docs/latest/", None),
     "matplotlib": ("http://matplotlib.org/", None),
@@ -152,12 +168,14 @@ def autolog(message):
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
 
-# plot directive options (extension: matplotlib.sphinxext.plot_directive ---
+# -- plot_directive extension -------------------------------------------------
+# See https://matplotlib.org/3.1.3/devel/plot_directive.html#options
 plot_formats = [
     ("png", 100),
 ]
 
 # -- Extlinks extension -------------------------------------------------------
+# See https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 
 extlinks = {
     "issue": ("https://github.com/SciTools/iris/issues/%s", "Issue #"),
@@ -220,6 +238,7 @@ def autolog(message):
 html_style = "theme_override.css"
 
 # url link checker.  Some links work but report as broken, lets ignore them.
+# See https://www.sphinx-doc.org/en/1.2/config.html#options-for-the-linkcheck-builder
 linkcheck_ignore = [
     "https://github.com/SciTools/iris/commit/69597eb3d8501ff16ee3d56aef1f7b8f1c2bb316#diff-1680206bdc5cfaa83e14428f5ba0f848",
     "http://www.wmo.int/pages/prog/www/DPFS/documents/485_Vol_I_en_colour.pdf",
@@ -230,6 +249,7 @@ def autolog(message):
 exclude_patterns = []
 
 # -- sphinx-gallery config ----------------------------------------------------
+# See https://sphinx-gallery.github.io/stable/configuration.html
 
 sphinx_gallery_conf = {
     # path to your example scripts
@@ -242,6 +262,8 @@ def autolog(message):
     "ignore_pattern": r"__init__\.py",
 }
 
+
+# -----------------------------------------------------------------------------
 # Remove matplotlib agg warnings from generated doc when using plt.show
 warnings.filterwarnings(
     "ignore",

diff --git a/docs/iris/src/developers_guide/contributing_documentation.rst b/docs/iris/src/developers_guide/contributing_documentation.rst
@@ -53,7 +53,7 @@ If you wish to run a clean build you can run::
     make clean
     make html
 
-This is useful for a final test before commiting your changes.
+This is useful for a final test before committing your changes.
 
 .. note:: In addition to the automated `travis-ci`_  build of the documentation, 
           the https://readthedocs.org/ service is also used.  The configuration 
@@ -68,41 +68,55 @@ This is useful for a final test before commiting your changes.
 Testing
 -------
 
-There are three ways to test various aspects of the documentation.
+There are a ways to test various aspects of the documentation.  The
+``make`` commands shown below can be run in the ``iris/docs/iris`` or
+``iris/docs/iris/src`` directory.
 
 Each :ref:`contributing.documentation.gallery` entry has a corresponding test.  
-The below command must be run in the ``iris/docs/iris`` directory::
+To run the tests::
 
     make gallerytest
 
-Many documentation pages includes python code itself that can be run to ensure it 
-is still valid.  The below command can be run in the ``iris/docs/iris`` or
-``iris/docs/iris/src`` directory::
+Many documentation pages includes python code itself that can be run to ensure
+it is still valid::
 
     make doctest
 
-Finally, all the hyperlinks in the documentation can be checked automatically.
+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 <https://github.com/SciTools/iris/blob/master/docs/iris/src/conf.py>`_.
-The hyperlink check can be run via::
+`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:: All of the above tests are automatically run as part of the 
           `travis-ci`_  automated build.
 
+.. _conf.py: https://github.com/SciTools/iris/blob/master/docs/iris/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 
+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 
 ``iris/docs/iris/src/sphinxext``.  Once the ``make html`` command has been run, 
 the output of these scripts can be found in
 ``iris/docs/iris/src/_build/generated/api``.
@@ -130,17 +144,17 @@ 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 
 ``iris/docs/iris/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 directoy and place it in
-there.
+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
 ``iris/docs/iris/src/_build/generated/gallery``.
 
 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.
+`sphinx-gallery getting started
+<https://sphinx-gallery.github.io/stable/getting_started.html>`_ documentation.
 
 
 

diff --git a/docs/iris/src/developers_guide/documenting/docstrings.rst b/docs/iris/src/developers_guide/documenting/docstrings.rst
@@ -1,9 +1,9 @@
-===========
- Docstrings
-===========
+==========
+Docstrings
+==========
 
-
-Guiding principle: Every public object in the Iris package should have an appropriate docstring.
+Guiding principle: Every public object in the Iris package should have an
+appropriate docstring.
 
 This document has been influenced by the following PEP's,
 
@@ -35,7 +35,7 @@ The multi-line docstring  *description section* should expand on what was stated
 
 Sample multi-line docstring
 ---------------------------
-Here is a simple example of a standard dosctring:
+Here is a simple example of a standard docstring:
 
 .. literalinclude:: docstrings_sample_routine.py
 
@@ -58,7 +58,7 @@ Documenting classes
 ===================
 The class constructor should be documented in the docstring for its ``__init__`` or ``__new__`` method. Methods should be documented by their own docstring, not in the class header itself.
 
-If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarise the differences. Use the verb "override" to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method (in addition to its own behavior).
+If a class subclasses another class and its behaviour is mostly inherited from that class, its docstring should mention this and summarise the differences. Use the verb "override" to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method (in addition to its own behaviour).
 
 
 Attribute and property docstrings

diff --git a/docs/iris/src/developers_guide/documenting/rest_guide.rst b/docs/iris/src/developers_guide/documenting/rest_guide.rst
@@ -1,6 +1,6 @@
-===============
-reST quickstart
-===============
+================
+reST quick start
+================
 
 
 reST (http://en.wikipedia.org/wiki/ReStructuredText) is a lightweight markup

diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst
@@ -42,7 +42,7 @@ what's :ref:`iris_whatsnew` entries.
 
 .. note:: The reStructuredText syntax will be checked as part of building
           the documentation.  Any warnings should be corrected.  
-          `travis-ci`_ will automatically build the documention when
+          `travis-ci`_ will automatically build the documentation when
           creating a pull request, however you can also manually 
           :ref:`build <contributing.documentation.building>` the documentation.
 

diff --git a/docs/iris/src/developers_guide/gitwash/configure_git.rst b/docs/iris/src/developers_guide/gitwash/configure_git.rst
@@ -55,7 +55,7 @@ In detail
 user.name and user.email
 ------------------------
 
-It is good practice to tell git_ who you are, for labeling any changes
+It is good practice to tell git_ who you are, for labelling any changes
 you make to the code.  The simplest way to do this is from the command
 line::
 

diff --git a/docs/iris/src/developers_guide/gitwash/development_workflow.rst b/docs/iris/src/developers_guide/gitwash/development_workflow.rst
@@ -148,7 +148,7 @@ Testing your changes
 ====================
 
 Once you are happy with your changes, work thorough the :ref:`pr_check` and make sure
-your branch passess all the relevant tests.
+your branch passes all the relevant tests.
 
 Ask for your changes to be reviewed or merged
 =============================================

diff --git a/docs/iris/src/developers_guide/graphics_tests.rst b/docs/iris/src/developers_guide/graphics_tests.rst
@@ -112,7 +112,7 @@ you should follow:
 
 #. Now re-run the tests.  The 'new' result should now be recognised and the
    relevant test should pass.  However, some tests can perform *multiple* graphics
-   checks within a single testcase function : In those cases, any failing
+   checks within a single test case function : In those cases, any failing
    check will prevent the following ones from being run, so a test re-run may
    encounter further (new) graphical test failures.  If that happens, simply
    repeat the check-and-accept process until all tests pass.

diff --git a/docs/iris/src/developers_guide/pulls.rst b/docs/iris/src/developers_guide/pulls.rst
@@ -1,5 +1,6 @@
 .. _pr_check:
 
+
 Pull request check List
 ***********************
 
@@ -33,17 +34,17 @@ The Iris check list
 
 * Have new tests been provided for all additional functionality?
 
-* Do all modified and new sourcefiles pass PEP8?
+* Do all modified and new source files pass PEP8?
 
  * PEP8_ is the Python source code style guide.
  * There is a python module for checking pep8 compliance: python-pep8_
- * a standard Iris test checks that all sourcefiles meet PEP8 compliance
+ * a standard Iris test checks that all source files meet PEP8 compliance
    (see "iris.tests.test_coding_standards.TestCodeFormat").
 
-* Do all modified and new sourcefiles have a correct, up-to-date copyright
+* Do all modified and new source files have a correct, up-to-date copyright
   header?
 
- * a standard Iris test checks that all sourcefiles include a copyright
+ * a standard Iris test checks that all source files include a copyright
    message, including the correct year of the latest change
    (see "iris.tests.test_coding_standards.TestLicenseHeaders").
 
@@ -64,7 +65,7 @@ The Iris check list
   * The documentation tests may be run with ``make doctest``, from within the
     ``./docs/iris`` subdirectory.
 
-* Have you provided a 'whats new' contribution?
+* Have you provided a "what's new" contribution?
 
  * this should be done for all changes that affect API or behaviour.
    See :ref:`whats_new_contributions`

diff --git a/docs/iris/src/developers_guide/release.rst b/docs/iris/src/developers_guide/release.rst
@@ -150,7 +150,7 @@ Post release steps
    triggered by any commit to master.  Additionally check that the versions
    available in the pop out menu in the bottom left corner include the new
    release version.  If it is not present you will need to configure the
-   versions avaiable in the **admin** dashboard in Read The Docs
+   versions available in the **admin** dashboard in Read The Docs
 #. Copy ``docs/iris/src/whatsnew/latest.rst.template`` to 
    ``docs/iris/src/whatsnew/latest.rst``.  This will reset
    the file with the ``unreleased`` heading and placeholders for the what's