diff --git a/.travis.yml b/.travis.yml index 604dbbb353..30490c5101 100644 --- 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 index 4ab54b291f..e9632ddb9f 100644 --- 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 index 7d8fb60e81..02263dc5e5 100644 --- 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 `_, 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 index 5589cce730..0aa921fd2a 100644 --- 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 index b28f5fbb7d..9b061f5ec6 100644 --- 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 index b7bc99b647..618e5fbd08 100644 --- 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 `_. -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 `_ -documentation. +`sphinx-gallery getting started +`_ documentation. diff --git a/docs/iris/src/developers_guide/documenting/docstrings.rst b/docs/iris/src/developers_guide/documenting/docstrings.rst index afc56014ea..641bf7717e 100644 --- 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 index e42e27c18e..aadb5ffea4 100644 --- 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 index 811aeb59cc..b4ca483075 100644 --- 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 ` the documentation. diff --git a/docs/iris/src/developers_guide/gitwash/configure_git.rst b/docs/iris/src/developers_guide/gitwash/configure_git.rst index 0e18b666d0..fd3cf0db20 100644 --- 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 index 312e114188..dee06454a1 100644 --- 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 index e84a59d48d..8f63bd3381 100644 --- 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 index 62535d27c6..366cedd159 100644 --- 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 index c44a248352..d71f149186 100644 --- 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 diff --git a/docs/iris/src/spelling_allow.txt b/docs/iris/src/spelling_allow.txt new file mode 100644 index 0000000000..6ef4134699 --- /dev/null +++ b/docs/iris/src/spelling_allow.txt @@ -0,0 +1,356 @@ +Admin +Albers +Arakawa +Arg +Args +Autoscale +Biggus +CF +Cartopy +Checklist +Color +Conda +Constraining +DAP +Dask +Debian +Duchon +EO +Eos +Exner +Fieldsfile +Fieldsfiles +FillValue +Gb +GeogCS +Hovmoller +Jul +Jun +Jupyter +Lanczos +Mappables +Matplotlib +Mb +Modeling +Mollweide +NetCDF +Nino +PPfield +PPfields +Perez +Proj +Quickplot +Regrids +Royer +Scitools +Scitools +Sep +Stehfest +Steroegraphic +Subsetting +TestCodeFormat +TestLicenseHeaders +Torvalds +Trans +Trenberth +Tri +URIs +URLs +Ubuntu +Ugrid +Unidata +Vol +Vuuren +Workflow +Yury +Zaytsev +Zorder +abf +abl +advection +aggregator +aggregators +alphap +ancils +antimeridian +ap +arg +args +arithmetic +arraylike +atol +auditable +aux +basemap +behaviour +betap +bhulev +biggus +blev +boolean +boundpoints +branchname +broadcastable +bugfix +bugfixes +builtin +bulev +carrée +cartesian +celsius +center +centrepoints +cf +cftime +chunksizes +clabel +cmap +cmpt +codebase +color +colorbar +colorbars +complevel +conda +config +constraining +convertor +coord +coords +cs +datafiles +datatype +datetime +datetimes +ddof +deepcopy +deprecations +der +dewpoint +dict +dicts +diff +discontiguities +discontiguous +djf +docstring +docstrings +doi +dom +dropdown +dtype +dtypes +dx +dy +edgecolor +endian +endianness +equirectangular +eta +etc +fh +fieldsfile +fieldsfiles +fileformat +fileformats +filename +filenames +filepath +filespec +fullname +func +geolocations +github +gregorian +grib +gribapi +gridcell +griddata +gridlines +hPa +hashable +hindcast +hyperlink +hyperlinks +idiff +ieee +ifunc +imagehash +init +inline +inplace +int +interable +interpolator +ints +io +isosurfaces +iterable +jja +kwarg +kwargs +landsea +lat +latlon +latlons +lats +lbcode +lbegin +lbext +lbfc +lbft +lblrec +lbmon +lbmond +lbnrec +lbrsvd +lbtim +lbuser +lbvc +lbyr +lbyrd +lh +lhs +linewidth +linted +linting +lon +lons +lt +mam +markup +matplotlib +matplotlibrc +max +mdtol +meaned +mercator +metadata +min +mpl +nanmask +nc +ndarray +neighbor +ness +netCDF +netcdf +netcdftime +nimrod +np +nsigma +numpy +nx +ny +online +orog +paramId +params +parsable +pcolormesh +pdf +placeholders +plugin +png +proj +ps +pseudocolor +pseudocolour +pseudocoloured +py +pyplot +quickplot +rST +rc +rd +reST +reStructuredText +rebase +rebases +rebasing +regrid +regridded +regridder +regridders +regridding +regrids +rel +repo +repos +reprojecting +rh +rhs +rst +rtol +scipy +scitools +seekable +setup +sines +sinh +spec +specs +src +ssh +st +stashcode +stashcodes +stats +std +stdout +str +subcube +subcubes +submodule +submodules +subsetting +sys +tanh +tb +testcases +tgt +th +timepoint +timestamp +timesteps +tol +tos +traceback +travis +tripolar +tuple +tuples +txt +udunits +ufunc +ugrid +ukmo +un +unhandled +unicode +unittest +unrotate +unrotated +uris +url +urls +util +var +versioning +vmax +vmin +waypoint +waypoints +whitespace +wildcard +wildcards +windspeeds +withnans +workflow +workflows +xN +xx +xxx +zeroth +zlev +zonal \ No newline at end of file diff --git a/docs/iris/src/techpapers/change_management.rst b/docs/iris/src/techpapers/change_management.rst index 2218eb4212..d09237a4bf 100644 --- a/docs/iris/src/techpapers/change_management.rst +++ b/docs/iris/src/techpapers/change_management.rst @@ -51,7 +51,7 @@ Checklist : * when a new **minor version is released** - * review the 'Whats New' documentation to see if it introduces any + * review the 'What's New' documentation to see if it introduces any deprecations that may affect you. * run your working legacy code and check for any deprecation warnings, indicating that modifications may be necessary at some point @@ -227,7 +227,7 @@ are : * A non-zero "" denotes a bugfix version, thus a release "X.Y.0" may be followed by "X.Y.1", "X.Y.2" etc, which *only* differ by containing - bugfixes. Any bugfix release supercedes its predecessors, and does not + bugfixes. Any bugfix release supersedes its predecessors, and does not change any (valid) APIs or behaviour : hence, it is always advised to replace a given version with its latest bugfix successor, and there should be no reason not to. @@ -261,7 +261,7 @@ behaviour of existing code can only be made at a **major** release, i.e. when "X.0" is released following the last previous "(X-1).Y.Z". *Minor* releases, by contrast, consist of bugfixes, new features, and -deprecations : Any valid exisiting code should be unaffected by these, so it +deprecations : Any valid existing code should be unaffected by these, so it will still run with the same results. At a major release, only **deprecated** behaviours and APIs can be changed or @@ -361,7 +361,7 @@ with the new release, which we obviously need to avoid. * the user code usage is simply by calls to "iris.load" * the change is not a bugfix, as the old way isn't actually "wrong" * we don't want to add an extra keyword into all the relevant calls - * we don't see a longterm future for the existing behaviour : we + * we don't see a long term future for the existing behaviour : we expect everyone to adopt the new interpretation, eventually For changes of this sort, the release will define a new boolean property of the @@ -427,7 +427,7 @@ At (major) release ".0...": * If your code is explicitly turning the option off, it will continue to work in the same way at this point, but obviously time is - runnning out. + running out. * If your code is still using the old behaviour and *not* setting the control option at all, its behaviour might now have changed diff --git a/docs/iris/src/techpapers/um_files_loading.rst b/docs/iris/src/techpapers/um_files_loading.rst index fd2d2a2341..d8c796b31f 100644 --- a/docs/iris/src/techpapers/um_files_loading.rst +++ b/docs/iris/src/techpapers/um_files_loading.rst @@ -30,7 +30,7 @@ Notes: #. Iris treats Fieldsfile data almost exactly as if it were PP -- i.e. it treats each field's lookup table entry like a PP header. -#. The Iris datamodel is based on +#. The Iris data model is based on `NetCDF CF conventions `_, so most of this can also be seen as a metadata translation between PP and CF terms, but it is easier to discuss in terms of Iris elements. @@ -132,7 +132,7 @@ For an ordinary latitude-longitude grid, the cubes have coordinates called ``ZDX/Y + BDX/Y * (1 .. LBNPT/LBROW)`` (*except*, if BDX/BDY is zero, the values are taken from the extra data vector X/Y, if present). * If X/Y_LOWER_BOUNDS extra data is available, this appears as bounds values - of the horizontal cooordinates. + of the horizontal coordinates. For **rotated** latitude-longitude coordinates (as for LBCODE=101), the horizontal coordinates differ only slightly -- diff --git a/docs/iris/src/userguide/code_maintenance.rst b/docs/iris/src/userguide/code_maintenance.rst index f5914da471..d03808e18f 100644 --- a/docs/iris/src/userguide/code_maintenance.rst +++ b/docs/iris/src/userguide/code_maintenance.rst @@ -9,18 +9,18 @@ Stability and change --------------------- In practice, as Iris develops, most users will want to periodically upgrade -their installed version to access new features or at least bugfixes. +their installed version to access new features or at least bug fixes. This is obvious if you are still developing other code that uses Iris, or using code from other sources. However, even if you have only legacy code that remains untouched, some code -maintenance effort is probably still necessary : +maintenance effort is probably still necessary: * On the one hand, *in principle*, working code will go on working, as long as you don't change anything else. - * However, such "version statis" can easily become a growing burden, if you - are simply waiting until an update becomes unavoidable : Often, that will + * However, such "version stasis" can easily become a growing burden, if you + are simply waiting until an update becomes unavoidable, often that will eventually occur when you need to update some other software component, for some completely unconnected reason. diff --git a/docs/iris/src/userguide/cube_statistics.rst b/docs/iris/src/userguide/cube_statistics.rst index 31e165d35c..310551c76f 100644 --- a/docs/iris/src/userguide/cube_statistics.rst +++ b/docs/iris/src/userguide/cube_statistics.rst @@ -245,7 +245,7 @@ These two coordinates can now be used to aggregate by season and climate-year: The primary change in the cube is that the cube's data has been reduced in the 'time' dimension by aggregation (taking means, in this case). -This has collected together all datapoints with the same values of season and +This has collected together all data points with the same values of season and season-year. The results are now indexed by the 19 different possible values of season and season-year in a new, reduced 'time' dimension. diff --git a/docs/iris/src/userguide/interpolation_and_regridding.rst b/docs/iris/src/userguide/interpolation_and_regridding.rst index 565f9b61eb..65ac36eada 100644 --- a/docs/iris/src/userguide/interpolation_and_regridding.rst +++ b/docs/iris/src/userguide/interpolation_and_regridding.rst @@ -1,6 +1,5 @@ .. _interpolation_and_regridding: - .. testsetup:: * import numpy as np @@ -16,7 +15,7 @@ Iris provides powerful cube-aware interpolation and regridding functionality, exposed through Iris cube methods. This functionality is provided by building upon existing interpolation schemes implemented by SciPy. -In Iris we refer to the avaliable types of interpolation and regridding as +In Iris we refer to the available types of interpolation and regridding as `schemes`. The following are the interpolation schemes that are currently available in Iris: diff --git a/docs/iris/src/userguide/loading_iris_cubes.rst b/docs/iris/src/userguide/loading_iris_cubes.rst index bbb83194db..006a919408 100644 --- a/docs/iris/src/userguide/loading_iris_cubes.rst +++ b/docs/iris/src/userguide/loading_iris_cubes.rst @@ -269,7 +269,7 @@ boundary of a circular coordinate (this is often the meridian or the dateline / antimeridian). An example use-case of this is to extract the entire Pacific Ocean from a cube whose longitudes are bounded by the dateline. -This functionality cannot be provided reliably using contraints. Instead you should use the +This functionality cannot be provided reliably using constraints. Instead you should use the functionality provided by :meth:`cube.intersection ` to extract this region. diff --git a/docs/iris/src/whatsnew/1.10.rst b/docs/iris/src/whatsnew/1.10.rst index 6413323203..b5dfc1974b 100644 --- a/docs/iris/src/whatsnew/1.10.rst +++ b/docs/iris/src/whatsnew/1.10.rst @@ -207,12 +207,12 @@ Bugs fixed * A bug that prevented cube printing in some cases has been fixed. * Fixed a bug where a deepcopy of a :class:`~iris.coords.DimCoord` would have - writable ``points`` and ``bounds`` arrays. These arrays can now no longer be + writeable ``points`` and ``bounds`` arrays. These arrays can now no longer be modified in-place. * Concatenation no longer occurs when the auxiliary coordinates of the cubes do not match. This check is not applied to AuxCoords that span the dimension the - concatenation is occuring along. This behaviour can be switched off by + concatenation is occurring along. This behaviour can be switched off by setting the ``check_aux_coords`` kwarg in :meth:`iris.cube.CubeList.concatenate` to False. @@ -240,7 +240,7 @@ Deprecations * Deprecated the module :mod:`iris.fileformats.grib`. The new package `iris_grib `_ replaces this - fuctionality, which will shortly be removed. + functionality, which will shortly be removed. Please see :ref:`iris_grib package `, above. * The use of :data:`iris.config.SAMPLE_DATA_DIR` has been deprecated and diff --git a/docs/iris/src/whatsnew/1.3.rst b/docs/iris/src/whatsnew/1.3.rst index 9e898a2b23..fd6f2cfef9 100644 --- a/docs/iris/src/whatsnew/1.3.rst +++ b/docs/iris/src/whatsnew/1.3.rst @@ -66,7 +66,7 @@ netCDF file. The following keys within the ``iris.site_configuration`` dictionary have been **reserved** as hooks to *external* user-defined CF profile functions: - * ``cf_profile`` injests a :class:`iris.cube.Cube` for analysis and returns a + * ``cf_profile`` ingests a :class:`iris.cube.Cube` for analysis and returns a profile result * ``cf_patch`` modifies the CF-netCDF file associated with export of the :class:`iris.cube.Cube` diff --git a/docs/iris/src/whatsnew/1.4.rst b/docs/iris/src/whatsnew/1.4.rst index 23b70b10c9..7f96643f5f 100644 --- a/docs/iris/src/whatsnew/1.4.rst +++ b/docs/iris/src/whatsnew/1.4.rst @@ -118,7 +118,7 @@ For example:: .. _iris-pandas: -Iris-Pandas interoperablilty +Iris-Pandas interoperability ---------------------------- Conversion to and from Pandas Series_ and DataFrames_ is now available. diff --git a/docs/iris/src/whatsnew/1.5.rst b/docs/iris/src/whatsnew/1.5.rst index c891e6c7ef..07f54e15cf 100644 --- a/docs/iris/src/whatsnew/1.5.rst +++ b/docs/iris/src/whatsnew/1.5.rst @@ -175,7 +175,7 @@ Bugs fixed * Coding of maximum and minimum time-stats in GRIB2 saving has been fixed. -* Example code in section 4.1 of the userguide updated so it uses a sample +* Example code in section 4.1 of the user guide updated so it uses a sample data file that exists. * Zorder of contour lines drawn by :func:`~iris.plot.contourf` has been changed diff --git a/docs/iris/src/whatsnew/1.7.rst b/docs/iris/src/whatsnew/1.7.rst index 22d9b05257..e60c1083d9 100644 --- a/docs/iris/src/whatsnew/1.7.rst +++ b/docs/iris/src/whatsnew/1.7.rst @@ -218,13 +218,13 @@ Bugs fixed vertical coordinates. * Auxiliary coordinate factory loading now correctly interprets formula term - varibles for "atmosphere hybrid sigma pressure" coordinate data. + variables for "atmosphere hybrid sigma pressure" coordinate data. * Corrected comparison of NumPy NaN values in cube merge process. * Fixes for :meth:`iris.cube.Cube.intersection` to correct calculating the intersection of a cube with split bounds, handling of circular coordinates, - handling of monotonically descending bounded coordinats and for finding a + handling of monotonically descending bounded coordinates and for finding a wrapped two-point result and longitude tolerances. * A bug affecting :meth:`iris.cube.Cube.extract` and diff --git a/docs/iris/src/whatsnew/1.9.rst b/docs/iris/src/whatsnew/1.9.rst index da3fabe613..77d03b5de3 100644 --- a/docs/iris/src/whatsnew/1.9.rst +++ b/docs/iris/src/whatsnew/1.9.rst @@ -26,7 +26,7 @@ Features whitespace before the colon. This is not strictly in the CF spec, but is a common occurrence. -* Basic cube arithemetic (plus, minus, times, divide) now supports lazy +* Basic cube arithmetic (plus, minus, times, divide) now supports lazy evaluation. * :meth:`iris.analysis.cartography.rotate_winds` can now operate much faster diff --git a/docs/iris/src/whatsnew/2.3.rst b/docs/iris/src/whatsnew/2.3.rst index 7c5a5c27b2..914d86fda2 100644 --- a/docs/iris/src/whatsnew/2.3.rst +++ b/docs/iris/src/whatsnew/2.3.rst @@ -85,7 +85,7 @@ Features previously could produce a large number of small chunks. This had an adverse effect on performance. - In addition, Iris now takes its default chunksize from the default configured + In addition, Iris now takes its default chunk size from the default configured in Dask itself, i.e. ``dask.config.get('array.chunk-size')``. .. admonition:: Lazy Statistics @@ -258,7 +258,7 @@ Documentation should not be relied on. * Fixed references in the documentation of - :func:`iris.util.find_discontiguities` to a nonexistent + :func:`iris.util.find_discontiguities` to a non existent "mask_discontiguities" routine : these now refer to :func:`~iris.util.mask_cube`. diff --git a/docs/iris/src/whatsnew/2.4.rst b/docs/iris/src/whatsnew/2.4.rst index 0df2a909ff..ca7be20cd8 100644 --- a/docs/iris/src/whatsnew/2.4.rst +++ b/docs/iris/src/whatsnew/2.4.rst @@ -33,7 +33,7 @@ Features * The area weights used when performing area weighted regridding with :class:`iris.analysis.AreaWeighted` are now cached. This allows a - significant speedup when regridding multiple similar cubes, by repeatedly + significant speed up when regridding multiple similar cubes, by repeatedly using a :func:`iris.analysis.AreaWeighted.regridder` objects which you created first. @@ -57,7 +57,7 @@ Bugs fixed * Fixed a problem which was causing file loads to fetch *all* field data whenever UM files (PP or Fieldsfiles) were loaded. - With large sourcefiles, initial file loads are slow, with large memory usage + With large source files, initial file loads are slow, with large memory usage before any cube data is even fetched. Large enough files will cause a crash. The problem occurs only with Dask versions >= 2.0. diff --git a/lib/iris/analysis/__init__.py b/lib/iris/analysis/__init__.py index 12560cefda..c94baf0a92 100644 --- a/lib/iris/analysis/__init__.py +++ b/lib/iris/analysis/__init__.py @@ -605,7 +605,7 @@ def update_metadata(self, cube, coords, **kwargs): Kwargs: - * This function is intended to be used in conjuction with aggregate() + * This function is intended to be used in conjunction with aggregate() and should be passed the same keywords (for example, the "ddof" keyword for a standard deviation aggregator). @@ -981,7 +981,7 @@ def update_metadata(self, cube, coords, **kwargs): Kwargs: - * This function is intended to be used in conjuction with aggregate() + * This function is intended to be used in conjunction with aggregate() and should be passed the same keywords (for example, the "ddof" keyword for a standard deviation aggregator). diff --git a/lib/iris/analysis/_grid_angles.py b/lib/iris/analysis/_grid_angles.py index c7f084bc1b..261c93e8ef 100644 --- a/lib/iris/analysis/_grid_angles.py +++ b/lib/iris/analysis/_grid_angles.py @@ -147,11 +147,11 @@ def gridcell_angles(x, y=None, cell_angle_boundpoints="mid-lhs, mid-rhs"): connected by wraparound. Input can be either two arrays, two coordinates, or a single cube - containing two suitable coordinates identified with the 'x' and'y' axes. + containing two suitable coordinates identified with the 'x' and 'y' axes. Args: - The inputs (x [,y]) can be any of the folliwing : + The inputs (x [,y]) can be any of the following : * x (:class:`~iris.cube.Cube`): a grid cube with 2D X and Y coordinates, identified by 'axis'. diff --git a/lib/iris/aux_factory.py b/lib/iris/aux_factory.py index 0cc6bf068f..5b63ff53ed 100644 --- a/lib/iris/aux_factory.py +++ b/lib/iris/aux_factory.py @@ -972,7 +972,7 @@ def make_coord(self, coord_dims_func): Args: * coord_dims_func: - A callable which can return the list of dimesions relevant + A callable which can return the list of dimensions relevant to a given coordinate. See :meth:`iris.cube.Cube.coord_dims()`. """ diff --git a/lib/iris/coord_systems.py b/lib/iris/coord_systems.py index cc41b27b34..812dfae23e 100644 --- a/lib/iris/coord_systems.py +++ b/lib/iris/coord_systems.py @@ -126,12 +126,13 @@ def __init__( radius. If just two of semi_major_axis, semi_minor_axis, and - inverse_flattening are given the missing element is calulated from the + inverse_flattening are given the missing element is calculated from the formula: :math:`flattening = (major - minor) / major` Currently, Iris will not allow over-specification (all three ellipsoid - paramaters). + parameters). + Examples:: cs = GeogCS(6371229) diff --git a/lib/iris/coords.py b/lib/iris/coords.py index 8fbe1abf56..09569f4ba5 100644 --- a/lib/iris/coords.py +++ b/lib/iris/coords.py @@ -170,7 +170,7 @@ def copy(self, values=None): * values An array of values for the new dimensional metadata object. - This may be a different shape to the orginal values array being + This may be a different shape to the original values array being copied. """ diff --git a/lib/iris/cube.py b/lib/iris/cube.py index 7c28018512..cc833f8848 100644 --- a/lib/iris/cube.py +++ b/lib/iris/cube.py @@ -2835,7 +2835,7 @@ def intersection(self, *args, **kwargs): For ranges defined over "circular" coordinates (i.e. those where the `units` attribute has a modulus defined) the cube - will be "rolled" to fit where neccesary. + will be "rolled" to fit where necessary. .. warning:: diff --git a/lib/iris/fileformats/rules.py b/lib/iris/fileformats/rules.py index 1e6cac691e..07ed5eb8ce 100644 --- a/lib/iris/fileformats/rules.py +++ b/lib/iris/fileformats/rules.py @@ -28,7 +28,7 @@ class ConcreteReferenceTarget: """Everything you need to make a real Cube for a named reference.""" def __init__(self, name, transform=None): - #: The name used to connect references with referencees. + #: The name used to connect references with references. self.name = name #: An optional transformation to apply to the cubes. self.transform = transform diff --git a/lib/iris/io/__init__.py b/lib/iris/io/__init__.py index 36f79d32d3..31cd862d85 100644 --- a/lib/iris/io/__init__.py +++ b/lib/iris/io/__init__.py @@ -334,7 +334,7 @@ def find_saver(filespec): def save(source, target, saver=None, **kwargs): """ - Save one or more Cubes to file (or other writable). + Save one or more Cubes to file (or other writeable). Iris currently supports three file formats for saving, which it can recognise by filename extension: @@ -353,7 +353,7 @@ def save(source, target, saver=None, **kwargs): * source - A :class:`iris.cube.Cube`, :class:`iris.cube.CubeList` or sequence of cubes. - * target - A filename (or writable, depending on file format). + * target - A filename (or writeable, depending on file format). When given a filename or file, Iris can determine the file format. diff --git a/lib/iris/util.py b/lib/iris/util.py index 95afb251a5..2e69ca6f97 100644 --- a/lib/iris/util.py +++ b/lib/iris/util.py @@ -1061,7 +1061,7 @@ def clip_string(the_str, clip_length=70, rider="..."): Returns: The string clipped to the required length with a rider appended. - If the clip length was greater than the orignal string, the + If the clip length was greater than the original string, the original string is returned unaltered. """