'
- '
{}'
- ''
- '
')
-
- toc_template = ('
'
- '{}'
- '')
-
- random_image_content_template = '''
-// This file was automatically generated by gen_gallery.py & should not be
-// modified directly.
-
-images = new Array();
-
-{}
-
-'''
-
- random_image_template = "['{thumbfile}', '{full_image}', '{link}'];"
- random_image_join = 'images[{}] = {}'
-
- dirs = ('General', 'Meteorology', 'Oceanography')
-
- for subdir in dirs:
- rows.append(header_template.format(subdir, subdir, subdir))
- toc_rows.append(toc_template.format(subdir, subdir))
-
- origdir = os.path.join(os.path.dirname(outdir), rootdir, subdir)
- if not os.path.exists(origdir):
- origdir = os.path.join(os.path.dirname(outdir), 'plot_directive',
- rootdir, subdir)
- thumbdir = os.path.join(outdir, rootdir, subdir, 'thumbnails')
- if not os.path.exists(thumbdir):
- os.makedirs(thumbdir)
-
- data = []
-
- for filename in sorted(glob.glob(os.path.join(origdir, '*.png'))):
- if filename.endswith('hires.png'):
- continue
-
- path, filename = os.path.split(filename)
- basename, ext = os.path.splitext(filename)
- if basename in skips:
- continue
-
- # Create thumbnails based on images in tmpdir, and place them
- # within the build tree.
- orig_path = str(os.path.join(origdir, filename))
- thumb_path = str(os.path.join(thumbdir, filename))
- if out_of_date(orig_path, thumb_path) or True:
- thumbnails[orig_path] = thumb_path
-
- m = multiimage.match(basename)
- if m is not None:
- basename = m.group(1)
-
- data.append((subdir, basename,
- os.path.join(rootdir, subdir, 'thumbnails',
- filename)))
-
- for (subdir, basename, thumbfile) in data:
- if thumbfile is not None:
- anchor = os.path.basename(thumbfile)
- anchor = os.path.splitext(anchor)[0].replace('_', '-')
- link = 'examples/{}/{}.html#{}'.format(
- subdir,
- basename,
- anchor)
- rows.append(link_template.format(
- href=link,
- thumb_file=thumbfile,
- alternative_text=basename))
- random_image.append(random_image_template.format(
- link=link,
- thumbfile=thumbfile,
- basename=basename,
- full_image='_images/' + os.path.basename(thumbfile)))
-
- if len(data) == 0:
- warnings.warn('No thumbnails were found in {}'.format(subdir))
-
- # Close out the
opened up at the top of this loop.
- rows.append('
')
-
- # Generate JS list of images for front page.
- random_image_content = '\n'.join([random_image_join.format(i, line)
- for i, line in enumerate(random_image)])
- random_image_content = random_image_content_template.format(
- random_image_content)
- random_image_script_path = os.path.join(app.builder.srcdir,
- '_static',
- 'random_image.js')
- with open(random_image_script_path, 'w') as fh:
- fh.write(random_image_content)
-
- content = template.format('\n'.join(toc_rows),
- '\n'.join(rows))
-
- # Only write out the file if the contents have actually changed.
- # Otherwise, this triggers a full rebuild of the docs.
-
- gallery_path = os.path.join(app.builder.srcdir,
- '_templates',
- 'gallery.html')
- if os.path.exists(gallery_path):
- with open(gallery_path, 'r') as fh:
- regenerate = fh.read() != content
- else:
- regenerate = True
- if regenerate:
- with open(gallery_path, 'w') as fh:
- fh.write(content)
-
- for key in status_iterator(thumbnails, 'generating thumbnails... ',
- length=len(thumbnails)):
- image.thumbnail(key, thumbnails[key], 0.3)
-
-
-def setup(app):
- app.connect('env-updated', gen_gallery)
diff --git a/docs/iris/src/sphinxext/generate_package_rst.py b/docs/iris/src/sphinxext/generate_package_rst.py
index 0c6510c170..5ce9f6d014 100644
--- a/docs/iris/src/sphinxext/generate_package_rst.py
+++ b/docs/iris/src/sphinxext/generate_package_rst.py
@@ -8,11 +8,23 @@
import sys
import re
import inspect
+import ntpath
+
+# list of tuples for modules to exclude. Useful if the documentation throws
+# warnings, especially for experimental modules.
+exclude_modules = [
+ ("experimental/raster", "iris.experimental.raster") # gdal conflicts
+]
+
+
+# print to stdout, including the name of the python file
+def autolog(message):
+ print("[{}] {}".format(ntpath.basename(__file__), message))
document_dict = {
# Use autoclass for classes.
- 'class': '''
+ "class": """
{object_docstring}
..
@@ -22,20 +34,21 @@
:undoc-members:
:inherited-members:
-''',
- 'function': '''
+""",
+ "function": """
.. autofunction:: {object_name}
-''',
+""",
# For everything else, let automodule do some magic...
- None: '''
+ None: """
.. autodata:: {object_name}
-'''}
+""",
+}
-horizontal_sep = '''
+horizontal_sep = """
.. raw:: html
↑ top ↑
@@ -47,21 +60,22 @@
-->
-'''
+"""
def lookup_object_type(obj):
if inspect.isclass(obj):
- return 'class'
+ return "class"
elif inspect.isfunction(obj):
- return 'function'
+ return "function"
else:
return None
-def auto_doc_module(file_path, import_name, root_package,
- package_toc=None, title=None):
- doc = r'''.. _{import_name}:
+def auto_doc_module(
+ file_path, import_name, root_package, package_toc=None, title=None
+):
+ doc = r""".. _{import_name}:
{title_underline}
{title}
@@ -77,54 +91,66 @@ def auto_doc_module(file_path, import_name, root_package,
{module_elements}
+"""
-'''
if package_toc:
- sidebar = '''
-.. sidebar:: Modules in this package
-
+ sidebar = """
{package_toc_tree}
- '''.format(package_toc_tree=package_toc)
+ """.format(
+ package_toc_tree=package_toc
+ )
else:
- sidebar = ''
+ sidebar = ""
try:
mod = __import__(import_name)
except ImportError as e:
- message = r'''.. error::
+ message = r""".. error::
This module could not be imported. Some dependencies are missing::
- ''' + str(e)
- return doc.format(title=title or import_name,
- title_underline='=' * len(title or import_name),
- import_name=import_name, root_package=root_package,
- sidebar=sidebar, module_elements=message)
+ """ + str(
+ e
+ )
+ return doc.format(
+ title=title or import_name,
+ title_underline="=" * len(title or import_name),
+ import_name=import_name,
+ root_package=root_package,
+ sidebar=sidebar,
+ module_elements=message,
+ )
mod = sys.modules[import_name]
elems = dir(mod)
- if '__all__' in elems:
- document_these = [(attr_name, getattr(mod, attr_name))
- for attr_name in mod.__all__]
+ if "__all__" in elems:
+ document_these = [
+ (attr_name, getattr(mod, attr_name)) for attr_name in mod.__all__
+ ]
else:
- document_these = [(attr_name, getattr(mod, attr_name))
- for attr_name in elems
- if (not attr_name.startswith('_') and
- not inspect.ismodule(getattr(mod, attr_name)))]
+ document_these = [
+ (attr_name, getattr(mod, attr_name))
+ for attr_name in elems
+ if (
+ not attr_name.startswith("_")
+ and not inspect.ismodule(getattr(mod, attr_name))
+ )
+ ]
def is_from_this_module(arg):
- name = arg[0]
+ # name = arg[0]
obj = arg[1]
- return (hasattr(obj, '__module__') and
- obj.__module__ == mod.__name__)
+ return (
+ hasattr(obj, "__module__") and obj.__module__ == mod.__name__
+ )
- sort_order = {'class': 2, 'function': 1}
+ sort_order = {"class": 2, "function": 1}
# Sort them according to sort_order dict.
def sort_key(arg):
- name = arg[0]
+ # name = arg[0]
obj = arg[1]
return sort_order.get(lookup_object_type(obj), 0)
@@ -133,63 +159,81 @@ def sort_key(arg):
lines = []
for element, obj in document_these:
- object_name = import_name + '.' + element
+ object_name = import_name + "." + element
obj_content = document_dict[lookup_object_type(obj)].format(
object_name=object_name,
- object_name_header_line='+' * len(object_name),
- object_docstring=inspect.getdoc(obj))
+ object_name_header_line="+" * len(object_name),
+ object_docstring=inspect.getdoc(obj),
+ )
lines.append(obj_content)
lines = horizontal_sep.join(lines)
- module_elements = '\n'.join(' * :py:obj:`{}`'.format(element)
- for element, obj in document_these)
+ module_elements = "\n".join(
+ " * :py:obj:`{}`".format(element) for element, obj in document_these
+ )
lines = doc + lines
- return lines.format(title=title or import_name,
- title_underline='=' * len(title or import_name),
- import_name=import_name, root_package=root_package,
- sidebar=sidebar, module_elements=module_elements)
+ return lines.format(
+ title=title or import_name,
+ title_underline="=" * len(title or import_name),
+ import_name=import_name,
+ root_package=root_package,
+ sidebar=sidebar,
+ module_elements=module_elements,
+ )
def auto_doc_package(file_path, import_name, root_package, sub_packages):
- max_depth = 1 if import_name == 'iris' else 2
- package_toc = '\n '.join(sub_packages)
- package_toc = '''
+ max_depth = 1 if import_name == "iris" else 2
+ package_toc = "\n ".join(sub_packages)
+
+ package_toc = """
.. toctree::
:maxdepth: {:d}
:titlesonly:
+ :hidden:
{}
-'''.format(max_depth, package_toc)
+""".format(
+ max_depth, package_toc
+ )
- if '.' in import_name:
+ if "." in import_name:
title = None
else:
- title = import_name.capitalize() + ' reference documentation'
+ title = import_name.capitalize() + " API"
- return auto_doc_module(file_path, import_name, root_package,
- package_toc=package_toc, title=title)
+ return auto_doc_module(
+ file_path,
+ import_name,
+ root_package,
+ package_toc=package_toc,
+ title=title,
+ )
def auto_package_build(app):
root_package = app.config.autopackage_name
if root_package is None:
- raise ValueError('set the autopackage_name variable in the '
- 'conf.py file')
+ raise ValueError(
+ "set the autopackage_name variable in the " "conf.py file"
+ )
if not isinstance(root_package, list):
- raise ValueError('autopackage was expecting a list of packages to '
- 'document e.g. ["itertools"]')
+ raise ValueError(
+ "autopackage was expecting a list of packages to "
+ 'document e.g. ["itertools"]'
+ )
for package in root_package:
do_package(package)
def do_package(package_name):
- out_dir = package_name + os.path.sep
+ out_dir = "generated/api" + os.path.sep
# Import the root package. If this fails then an import error will be
# raised.
@@ -199,38 +243,45 @@ def do_package(package_name):
package_folder = []
module_folders = {}
+
for root, subFolders, files in os.walk(rootdir):
for fname in files:
name, ext = os.path.splitext(fname)
# Skip some non-relevant files.
- if (fname.startswith('.') or fname.startswith('#') or
- re.search('^_[^_]', fname) or fname.find('.svn') >= 0 or
- not (ext in ['.py', '.so'])):
+ if (
+ fname.startswith(".")
+ or fname.startswith("#")
+ or re.search("^_[^_]", fname)
+ or fname.find(".svn") >= 0
+ or not (ext in [".py", ".so"])
+ ):
continue
# Handle new shared library naming conventions
- if ext == '.so':
- name = name.split('.', 1)[0]
+ if ext == ".so":
+ name = name.split(".", 1)[0]
- rel_path = root_package + \
- os.path.join(root, fname).split(rootdir)[-1]
- mod_folder = root_package + \
- os.path.join(root).split(rootdir)[-1].replace('/', '.')
+ rel_path = (
+ root_package + os.path.join(root, fname).split(rootdir)[-1]
+ )
+ mod_folder = root_package + os.path.join(root).split(rootdir)[
+ -1
+ ].replace("/", ".")
# Only add this package to folder list if it contains an __init__
# script.
- if name == '__init__':
+ if name == "__init__":
package_folder.append([mod_folder, rel_path])
else:
- import_name = mod_folder + '.' + name
+ import_name = mod_folder + "." + name
mf_list = module_folders.setdefault(mod_folder, [])
mf_list.append((import_name, rel_path))
if not os.path.exists(out_dir):
os.makedirs(out_dir)
for package, package_path in package_folder:
- if '._' in package or 'test' in package:
+ if "._" in package or "test" in package:
continue
paths = []
@@ -242,60 +293,83 @@ def do_package(package_name):
continue
if not spackage.startswith(package):
continue
- if spackage.count('.') > package.count('.') + 1:
+ if spackage.count(".") > package.count(".") + 1:
continue
- if 'test' in spackage:
+ if "test" in spackage:
continue
- split_path = spackage.rsplit('.', 2)[-2:]
- if any(part[0] == '_' for part in split_path):
+ split_path = spackage.rsplit(".", 2)[-2:]
+ if any(part[0] == "_" for part in split_path):
continue
- paths.append(os.path.join(*split_path) + '.rst')
+ paths.append(os.path.join(*split_path) + ".rst")
- paths.extend(os.path.join(os.path.basename(os.path.dirname(path)),
- os.path.basename(path).split('.', 1)[0])
- for imp_name, path in module_folders.get(package, []))
+ paths.extend(
+ os.path.join(
+ os.path.basename(os.path.dirname(path)),
+ os.path.basename(path).split(".", 1)[0],
+ )
+ for imp_name, path in module_folders.get(package, [])
+ )
paths.sort()
+
+ # check for any modules to exclude
+ for exclude_module in exclude_modules:
+ if exclude_module[0] in paths:
+ autolog(
+ "Excluding module in package: {}".format(exclude_module[0])
+ )
+ paths.remove(exclude_module[0])
+
doc = auto_doc_package(package_path, package, root_package, paths)
- package_dir = out_dir + package.replace('.', os.path.sep)
+ package_dir = out_dir + package.replace(".", os.path.sep)
if not os.path.exists(package_dir):
- os.makedirs(out_dir + package.replace('.', os.path.sep))
+ os.makedirs(out_dir + package.replace(".", os.path.sep))
- out_path = package_dir + '.rst'
+ out_path = package_dir + ".rst"
if not os.path.exists(out_path):
- print('Creating non-existent document {} ...'.format(out_path))
- with open(out_path, 'w') as fh:
+ autolog("Creating {} ...".format(out_path))
+ with open(out_path, "w") as fh:
fh.write(doc)
else:
- with open(out_path, 'r') as fh:
- existing_content = ''.join(fh.readlines())
+ with open(out_path, "r") as fh:
+ existing_content = "".join(fh.readlines())
if doc != existing_content:
- print('Creating out of date document {} ...'.format(
- out_path))
- with open(out_path, 'w') as fh:
+ autolog("Creating {} ...".format(out_path))
+ with open(out_path, "w") as fh:
fh.write(doc)
for import_name, module_path in module_folders.get(package, []):
- doc = auto_doc_module(module_path, import_name, root_package)
- out_path = out_dir + import_name.replace('.', os.path.sep) + '.rst'
- if not os.path.exists(out_path):
- print('Creating non-existent document {} ...'.format(
- out_path))
- with open(out_path, 'w') as fh:
- fh.write(doc)
- else:
- with open(out_path, 'r') as fh:
- existing_content = ''.join(fh.readlines())
- if doc != existing_content:
- print('Creating out of date document {} ...'.format(
- out_path))
- with open(out_path, 'w') as fh:
- fh.write(doc)
+ # check for any modules to exclude
+ for exclude_module in exclude_modules:
+ if import_name == exclude_module[1]:
+ autolog(
+ "Excluding module file: {}".format(exclude_module[1])
+ )
+ else:
+ doc = auto_doc_module(
+ module_path, import_name, root_package
+ )
+ out_path = (
+ out_dir
+ + import_name.replace(".", os.path.sep)
+ + ".rst"
+ )
+ if not os.path.exists(out_path):
+ autolog("Creating {} ...".format(out_path))
+ with open(out_path, "w") as fh:
+ fh.write(doc)
+ else:
+ with open(out_path, "r") as fh:
+ existing_content = "".join(fh.readlines())
+ if doc != existing_content:
+ autolog("Creating {} ...".format(out_path))
+ with open(out_path, "w") as fh:
+ fh.write(doc)
def setup(app):
- app.connect('builder-inited', auto_package_build)
- app.add_config_value('autopackage_name', None, 'env')
+ app.connect("builder-inited", auto_package_build)
+ app.add_config_value("autopackage_name", None, "env")
diff --git a/docs/iris/src/whitepapers/change_management.rst b/docs/iris/src/techpapers/change_management.rst
similarity index 96%
rename from docs/iris/src/whitepapers/change_management.rst
rename to docs/iris/src/techpapers/change_management.rst
index b279c91b96..2218eb4212 100644
--- a/docs/iris/src/whitepapers/change_management.rst
+++ b/docs/iris/src/techpapers/change_management.rst
@@ -1,3 +1,5 @@
+:orphan:
+
.. _change_management:
Change Management in Iris from the User's perspective
@@ -44,25 +46,28 @@ User Actions : How you should respond to changes and releases
Checklist :
* when a new **testing or candidate version** is announced
- if convenient, test your working legacy code against it and report any problems.
+
+ * if convenient, test your working legacy code against it and report any problems.
* when a new **minor version is released**
- * review the 'Whats 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
- * when convenient :
+ * review the 'Whats 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
+ * when convenient :
* review existing code for use of deprecated features
* rewrite code to replace deprecated features
* when a new major version is **announced**
- ensure your code runs, without producing deprecation warnings, in the
+
+ * ensure your code runs, without producing deprecation warnings, in the
previous minor release
* when a new major version is **released**
- check for new deprecation warnings, as for a minor release
+
+ * check for new deprecation warnings, as for a minor release
Details
@@ -81,6 +86,7 @@ Our practices are intended be compatible with the principles defined in the
`SemVer project
`_ .
Key concepts covered here:
+
* :ref:`Release versions
`
* :ref:`Backwards compatibility `
* :ref:`Deprecation `
@@ -95,18 +101,18 @@ Backwards compatibility
usages unchanged (see :ref:`terminology ` below).
Minor releases may only include backwards-compatible changes.
-The following are examples of backward-compatible changes :
+The following are examples of backward-compatible changes:
* changes to documentation
* adding to a module : new submodules, functions, classes or properties
* adding to a class : new methods or properties
* adding to a function or method : new **optional** arguments or keywords
-The following are examples of **non-** backward-compatible changes :
+The following are examples of **non-** backward-compatible changes:
* removing (which includes *renaming*) any public module or submodule
* removing any public component : a module, class, method, function or
- data object property of a public API component
+ data object property of a public API component
* removing any property of a public object
* removing an argument or keyword from a method or function
* adding a required argument to a method or function
diff --git a/docs/iris/src/whitepapers/index.rst b/docs/iris/src/techpapers/index.rst
similarity index 54%
rename from docs/iris/src/whitepapers/index.rst
rename to docs/iris/src/techpapers/index.rst
index dd0876d257..773c8f7059 100644
--- a/docs/iris/src/whitepapers/index.rst
+++ b/docs/iris/src/techpapers/index.rst
@@ -1,8 +1,9 @@
-.. _whitepapers_index:
+.. _techpapers_index:
+
+
+Iris Technical Papers
+=====================
-============================
-Iris technical 'Whitepapers'
-============================
Extra information on specific technical issues.
.. toctree::
diff --git a/docs/iris/src/whitepapers/missing_data_handling.rst b/docs/iris/src/techpapers/missing_data_handling.rst
similarity index 100%
rename from docs/iris/src/whitepapers/missing_data_handling.rst
rename to docs/iris/src/techpapers/missing_data_handling.rst
diff --git a/docs/iris/src/whitepapers/um_files_loading.rst b/docs/iris/src/techpapers/um_files_loading.rst
similarity index 100%
rename from docs/iris/src/whitepapers/um_files_loading.rst
rename to docs/iris/src/techpapers/um_files_loading.rst
diff --git a/docs/iris/src/userguide/citation.rst b/docs/iris/src/userguide/citation.rst
index 01b655574e..7ce0a8ffc0 100644
--- a/docs/iris/src/userguide/citation.rst
+++ b/docs/iris/src/userguide/citation.rst
@@ -23,7 +23,7 @@ For example::
*******************
-Downloaded Software
+Downloaded software
*******************
Suggested format::
@@ -36,7 +36,7 @@ For example::
********************
-Checked out Software
+Checked out software
********************
Suggested format::
diff --git a/docs/iris/src/userguide/code_maintenance.rst b/docs/iris/src/userguide/code_maintenance.rst
index 00ba30506c..f5914da471 100644
--- a/docs/iris/src/userguide/code_maintenance.rst
+++ b/docs/iris/src/userguide/code_maintenance.rst
@@ -1,11 +1,11 @@
-Code Maintenance
+Code maintenance
================
From a user point of view "code maintenance" means ensuring that your existing
working code stays working, in the face of changes to Iris.
-Stability and Change
+Stability and change
---------------------
In practice, as Iris develops, most users will want to periodically upgrade
@@ -25,7 +25,7 @@ maintenance effort is probably still necessary :
for some completely unconnected reason.
-Principles of Change Management
+Principles of change management
-------------------------------
When you upgrade software to a new version, you often find that you need to
diff --git a/docs/iris/src/userguide/cube_maths.rst b/docs/iris/src/userguide/cube_maths.rst
index 8fe6eb12d5..6af4d5b3a6 100644
--- a/docs/iris/src/userguide/cube_maths.rst
+++ b/docs/iris/src/userguide/cube_maths.rst
@@ -208,7 +208,7 @@ The result could now be plotted using the guidance provided in the
.. only:: html
A very similar example to this can be found in
- :doc:`/examples/Meteorology/deriving_phenomena`.
+ :ref:`sphx_glr_generated_gallery_meteorology_plot_deriving_phenomena.py`.
.. only:: latex
diff --git a/docs/iris/src/userguide/cube_statistics.rst b/docs/iris/src/userguide/cube_statistics.rst
index 3ca7d9a2e0..31e165d35c 100644
--- a/docs/iris/src/userguide/cube_statistics.rst
+++ b/docs/iris/src/userguide/cube_statistics.rst
@@ -93,7 +93,8 @@ can be used instead of ``MEAN``, see :mod:`iris.analysis` for a full list
of currently supported operators.
For an example of using this functionality, the
-:ref:`Hovmoller diagram ` example found
+:ref:`sphx_glr_generated_gallery_meteorology_plot_hovmoller.py`
+example found
in the gallery takes a zonal mean of an ``XYT`` cube by using the
``collapsed`` method with ``latitude`` and ``iris.analysis.MEAN`` as arguments.
@@ -147,7 +148,7 @@ These areas can now be passed to the ``collapsed`` method as weights:
Several examples of area averaging exist in the gallery which may be of interest,
including an example on taking a :ref:`global area-weighted mean
-`.
+`.
.. _cube-statistics-aggregated-by:
diff --git a/docs/iris/src/userguide/end_of_userguide.rst b/docs/iris/src/userguide/end_of_userguide.rst
deleted file mode 100644
index c8f951a634..0000000000
--- a/docs/iris/src/userguide/end_of_userguide.rst
+++ /dev/null
@@ -1,15 +0,0 @@
-End of the user guide
-=====================
-
-If this was your first time reading the user guide, we hope you found it enjoyable and informative.
-It is advised that you now go back to the :doc:`start ` and try experimenting with your own data.
-
-
-
-Iris gallery
-------------
-It can be very daunting to start coding a project from an empty file, that is why you will find many in-depth
-examples in the Iris gallery which can be used as a goal driven reference to producing your own visualisations.
-
-If you produce a visualisation which you think would add value to the gallery, please get in touch with us and
-we will consider including it as an example for all to benefit from.
diff --git a/docs/iris/src/userguide/index.rst b/docs/iris/src/userguide/index.rst
index 4fb7b62155..2a3b32fe11 100644
--- a/docs/iris/src/userguide/index.rst
+++ b/docs/iris/src/userguide/index.rst
@@ -1,11 +1,9 @@
.. _user_guide_index:
+.. _user_guide_introduction:
-===============
-Iris user guide
-===============
+Introduction
+============
-How to use the user guide
----------------------------
If you are reading this user guide for the first time it is strongly recommended that you read the user guide
fully before experimenting with your own data files.
@@ -18,24 +16,16 @@ links in order to understand the guide but they may serve as a useful reference
Since later pages depend on earlier ones, try reading this user guide sequentially using the ``next`` and ``previous`` links.
-User guide table of contents
--------------------------------
-
-.. toctree::
- :maxdepth: 2
- :numbered:
-
- iris_cubes.rst
- loading_iris_cubes.rst
- saving_iris_cubes.rst
- navigating_a_cube.rst
- subsetting_a_cube.rst
- real_and_lazy_data.rst
- plotting_a_cube.rst
- interpolation_and_regridding.rst
- merge_and_concat.rst
- cube_statistics.rst
- cube_maths.rst
- citation.rst
- code_maintenance.rst
- end_of_userguide.rst
+* :doc:`iris_cubes`
+* :doc:`loading_iris_cubes`
+* :doc:`saving_iris_cubes`
+* :doc:`navigating_a_cube`
+* :doc:`subsetting_a_cube`
+* :doc:`real_and_lazy_data`
+* :doc:`plotting_a_cube`
+* :doc:`interpolation_and_regridding`
+* :doc:`merge_and_concat`
+* :doc:`cube_statistics`
+* :doc:`cube_maths`
+* :doc:`citation`
+* :doc:`code_maintenance`
diff --git a/docs/iris/src/userguide/iris_cubes.rst b/docs/iris/src/userguide/iris_cubes.rst
index dc423afba1..5929c402f2 100644
--- a/docs/iris/src/userguide/iris_cubes.rst
+++ b/docs/iris/src/userguide/iris_cubes.rst
@@ -1,13 +1,9 @@
-.. _user_guide_introduction:
-
-===================
-Introduction
-===================
-
.. _iris_data_structures:
+====================
Iris data structures
---------------------
+====================
+
The top level object in Iris is called a cube. A cube contains data and metadata about a phenomenon.
In Iris, a cube is an interpretation of the *Climate and Forecast (CF) Metadata Conventions* whose purpose is to:
@@ -33,6 +29,7 @@ by definition, its phenomenon.
* Each coordinate has a name and a unit.
* When a coordinate is added to a cube, the data dimensions that it represents are also provided.
+
* The shape of a coordinate is always the same as the shape of the associated data dimension(s) on the cube.
* A dimension not explicitly listed signifies that the coordinate is independent of that dimension.
* Each dimension of a coordinate must be mapped to a data dimension. The only coordinates with no mapping are
diff --git a/docs/iris/src/userguide/loading_iris_cubes.rst b/docs/iris/src/userguide/loading_iris_cubes.rst
index bf50acc614..bbb83194db 100644
--- a/docs/iris/src/userguide/loading_iris_cubes.rst
+++ b/docs/iris/src/userguide/loading_iris_cubes.rst
@@ -38,10 +38,12 @@ This shows that there were 2 cubes as a result of loading the file, they were:
``air_potential_temperature`` and ``surface_altitude``.
The ``surface_altitude`` cube was 2 dimensional with:
+
* the two dimensions have extents of 204 and 187 respectively and are
represented by the ``grid_latitude`` and ``grid_longitude`` coordinates.
The ``air_potential_temperature`` cubes were 4 dimensional with:
+
* the same length ``grid_latitude`` and ``grid_longitude`` dimensions as
``surface_altitide``
* a ``time`` dimension of length 3
diff --git a/docs/iris/src/userguide/merge_and_concat.rst b/docs/iris/src/userguide/merge_and_concat.rst
index b742b3ef5f..0d844ac403 100644
--- a/docs/iris/src/userguide/merge_and_concat.rst
+++ b/docs/iris/src/userguide/merge_and_concat.rst
@@ -1,7 +1,7 @@
.. _merge_and_concat:
=====================
-Merge and Concatenate
+Merge and concatenate
=====================
We saw in the :doc:`loading_iris_cubes` chapter that Iris tries to load as few cubes as
diff --git a/docs/iris/src/userguide/plotting_a_cube.rst b/docs/iris/src/userguide/plotting_a_cube.rst
index d82cbbb027..f646aa4b3e 100644
--- a/docs/iris/src/userguide/plotting_a_cube.rst
+++ b/docs/iris/src/userguide/plotting_a_cube.rst
@@ -190,7 +190,7 @@ and providing the label keyword to identify it.
Once all of the lines have been added the :func:`matplotlib.pyplot.legend`
function can be called to indicate that a legend is desired:
-.. plot:: ../example_code/General/lineplot_with_legend.py
+.. plot:: ../gallery_code/general/plot_lineplot_with_legend.py
:include-source:
This example of consecutive ``qplt.plot`` calls coupled with the
@@ -272,7 +272,7 @@ Brewer colour palettes
***********************
Iris includes colour specifications and designs developed by
-`Cynthia Brewer `_.
+`Cynthia Brewer `_
These colour schemes are freely available under the following licence::
Apache-Style Software License for ColorBrewer software and ColorBrewer Color Schemes
@@ -298,7 +298,7 @@ For adding citations to Iris plots, see :ref:`brewer-cite` (below).
Available Brewer Schemes
========================
The following subset of Brewer palettes found at
-`colorbrewer.org `_ are available within Iris.
+`colorbrewer2.org `_ are available within Iris.
.. plot:: userguide/plotting_examples/brewer.py
diff --git a/docs/iris/src/userguide/plotting_examples/1d_quickplot_simple.py b/docs/iris/src/userguide/plotting_examples/1d_quickplot_simple.py
index 30a5fc4318..f3772328ab 100644
--- a/docs/iris/src/userguide/plotting_examples/1d_quickplot_simple.py
+++ b/docs/iris/src/userguide/plotting_examples/1d_quickplot_simple.py
@@ -11,4 +11,5 @@
temperature_1d = temperature[5, :]
qplt.plot(temperature_1d)
+
plt.show()
diff --git a/docs/iris/src/userguide/plotting_examples/1d_simple.py b/docs/iris/src/userguide/plotting_examples/1d_simple.py
index b76752ac18..ea90faf402 100644
--- a/docs/iris/src/userguide/plotting_examples/1d_simple.py
+++ b/docs/iris/src/userguide/plotting_examples/1d_simple.py
@@ -11,4 +11,5 @@
temperature_1d = temperature[5, :]
iplt.plot(temperature_1d)
+
plt.show()
diff --git a/docs/iris/src/userguide/plotting_examples/1d_with_legend.py b/docs/iris/src/userguide/plotting_examples/1d_with_legend.py
index 1ee75e1ed9..26aeeef9a6 100644
--- a/docs/iris/src/userguide/plotting_examples/1d_with_legend.py
+++ b/docs/iris/src/userguide/plotting_examples/1d_with_legend.py
@@ -1,5 +1,4 @@
import matplotlib.pyplot as plt
-
import iris
import iris.plot as iplt
diff --git a/docs/iris/src/userguide/plotting_examples/brewer.py b/docs/iris/src/userguide/plotting_examples/brewer.py
index e4533a28f5..f2ede9f9bc 100644
--- a/docs/iris/src/userguide/plotting_examples/brewer.py
+++ b/docs/iris/src/userguide/plotting_examples/brewer.py
@@ -4,19 +4,26 @@
import iris.palette
-a = np.linspace(0, 1, 256).reshape(1, -1)
-a = np.vstack((a, a))
-
-maps = sorted(iris.palette.CMAP_BREWER)
-nmaps = len(maps)
-
-fig = plt.figure(figsize=(7, 10))
-fig.subplots_adjust(top=0.99, bottom=0.01, left=0.2, right=0.99)
-for i, m in enumerate(maps):
- ax = plt.subplot(nmaps, 1, i + 1)
- plt.axis("off")
- plt.imshow(a, aspect="auto", cmap=plt.get_cmap(m), origin="lower")
- pos = list(ax.get_position().bounds)
- fig.text(pos[0] - 0.01, pos[1], m, fontsize=8, horizontalalignment="right")
-
-plt.show()
+def main():
+ a = np.linspace(0, 1, 256).reshape(1, -1)
+ a = np.vstack((a, a))
+
+ maps = sorted(iris.palette.CMAP_BREWER)
+ nmaps = len(maps)
+
+ fig = plt.figure(figsize=(7, 10))
+ fig.subplots_adjust(top=0.99, bottom=0.01, left=0.2, right=0.99)
+ for i, m in enumerate(maps):
+ ax = plt.subplot(nmaps, 1, i + 1)
+ plt.axis("off")
+ plt.imshow(a, aspect="auto", cmap=plt.get_cmap(m), origin="lower")
+ pos = list(ax.get_position().bounds)
+ fig.text(
+ pos[0] - 0.01, pos[1], m, fontsize=8, horizontalalignment="right"
+ )
+
+ plt.show()
+
+
+if __name__ == "__main__":
+ main()
diff --git a/docs/iris/src/userguide/plotting_examples/cube_blockplot.py b/docs/iris/src/userguide/plotting_examples/cube_blockplot.py
index cd380f5e35..0961a97fdb 100644
--- a/docs/iris/src/userguide/plotting_examples/cube_blockplot.py
+++ b/docs/iris/src/userguide/plotting_examples/cube_blockplot.py
@@ -1,5 +1,4 @@
import matplotlib.pyplot as plt
-
import iris
import iris.quickplot as qplt
diff --git a/docs/iris/src/userguide/plotting_examples/cube_brewer_cite_contourf.py b/docs/iris/src/userguide/plotting_examples/cube_brewer_cite_contourf.py
index 6dce2b39de..45ba800485 100644
--- a/docs/iris/src/userguide/plotting_examples/cube_brewer_cite_contourf.py
+++ b/docs/iris/src/userguide/plotting_examples/cube_brewer_cite_contourf.py
@@ -1,5 +1,4 @@
import matplotlib.pyplot as plt
-
import iris
import iris.quickplot as qplt
import iris.plot as iplt
diff --git a/docs/iris/src/userguide/saving_iris_cubes.rst b/docs/iris/src/userguide/saving_iris_cubes.rst
index f14f83006e..fa67b6213d 100644
--- a/docs/iris/src/userguide/saving_iris_cubes.rst
+++ b/docs/iris/src/userguide/saving_iris_cubes.rst
@@ -97,7 +97,7 @@ netCDF
NetCDF is a flexible container for metadata and cube metadata is closely related to the CF for netCDF semantics. This means that cube metadata is well represented in netCDF files, closely resembling the in memory metadata representation.
Thus there is no provision for similar save customisation functionality for netCDF saving, all customisations should be applied to the cube prior to saving to netCDF.
-Bespoke Saver
+Bespoke saver
--------------
A bespoke saver may be written to support an alternative file format. This can be provided to the :py:func:`iris.save` function, enabling Iris to write to a different file format.
diff --git a/docs/iris/src/whatsnew/1.0.rst b/docs/iris/src/whatsnew/1.0.rst
index 2a415c1bfe..6340d0495d 100644
--- a/docs/iris/src/whatsnew/1.0.rst
+++ b/docs/iris/src/whatsnew/1.0.rst
@@ -69,7 +69,7 @@ CF-netCDF coordinate systems
============================
The coordinate systems in Iris are now defined by the CF-netCDF
-`grid mappings `_.
+`grid mappings `_.
As of Iris 1.0 a subset of the CF-netCDF coordinate systems are
supported, but this will be expanded in subsequent versions. Adding
this code is a relatively simple, incremental process - it would make a
@@ -79,13 +79,13 @@ contributing to the project.
The coordinate systems available in Iris 1.0 and their corresponding
Iris classes are:
-================================================================================================== =========================================
-CF name Iris class
-================================================================================================== =========================================
-`Latitude-longitude `_ :class:`~iris.coord_systems.GeogCS`
-`Rotated pole `_ :class:`~iris.coord_systems.RotatedGeogCS`
-`Transverse Mercator `_ :class:`~iris.coord_systems.TransverseMercator`
-================================================================================================== =========================================
+================================================================================================================= =========================================
+CF name Iris class
+================================================================================================================= =========================================
+`Latitude-longitude `_ :class:`~iris.coord_systems.GeogCS`
+`Rotated pole `_ :class:`~iris.coord_systems.RotatedGeogCS`
+`Transverse Mercator `_ :class:`~iris.coord_systems.TransverseMercator`
+================================================================================================================= =========================================
For convenience, Iris also includes the :class:`~iris.coord_systems.OSGB`
class which provides a simple way to create the transverse Mercator
@@ -147,8 +147,7 @@ Hybrid-pressure
With the introduction of the :class:`~iris.aux_factory.HybridPressureFactory`
class, it is now possible to represent data expressed on a
-hybrid-pressure vertical coordinate, as defined by the second variant in
-`Appendix D `_.
+`hybrid-pressure vertical coordinate `_.
A hybrid-pressure factory is created with references to the coordinates
which provide the components of the hybrid coordinate ("ap" and "b") and
the surface pressure. In return, it provides a virtual "pressure"
@@ -160,7 +159,7 @@ the derived "pressure" coordinate for certain data [#f1]_ from the
.. [#f1] Where the level type is either 105 or 119, and where the
surface pressure has an ECMWF paramId of
- `152 `_.
+ `152 `_.
NetCDF
diff --git a/docs/iris/src/whatsnew/1.10.rst b/docs/iris/src/whatsnew/1.10.rst
index 26f21c0252..bc2b7528b2 100644
--- a/docs/iris/src/whatsnew/1.10.rst
+++ b/docs/iris/src/whatsnew/1.10.rst
@@ -1,4 +1,4 @@
-What's New in Iris 1.10
+What's new in Iris 1.10
***********************
:Release: 1.10
@@ -7,7 +7,7 @@ What's New in Iris 1.10
This document explains the new/changed features of Iris in version 1.10
(:doc:`View all changes `.)
-Iris 1.10 Features
+Iris 1.10 features
==================
.. _iris_grib_added:
@@ -76,7 +76,7 @@ Iris 1.10 Features
* Cubes with anonymous dimensions can now be concatenated. This can only occur along a dimension that is not anonymous.
* NetCDF saving of ``valid_range``, ``valid_min`` and ``valid_max`` cube attributes is now allowed.
-Bugs Fixed
+Bugs fixed
==========
* Altered Cell Methods to display coordinate's standard_name rather than var_name where appropriate to avoid human confusion.
* Saving multiple cubes with netCDF4 protected attributes should now work as expected.
@@ -101,7 +101,7 @@ Bugs Fixed
* 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 setting the ``check_aux_coords`` kwarg in :meth:`iris.cube.CubeList.concatenate` to False.
* Fixed a bug in :meth:`iris.cube.Cube.subset` where an exception would be thrown while trying to subset over a non-dimensional scalar coordinate.
-Incompatible Changes
+Incompatible changes
====================
* The source and target for :meth:`iris.experimental.regrid.PointInCell.regridder` must now have defined coordinate systems (i.e. not ``None``). Additionally, the source data X and Y coordinates must have the same cube dimensions.
@@ -170,7 +170,7 @@ Documentation Changes
* It is now clear that repeated values will form a group under :meth:`iris.cube.Cube.aggregated_by` even if they aren't consecutive. Hence, the documentation for :mod:`iris.cube` has been changed to reflect this.
* The documentation for :meth:`iris.analysis.calculus.curl` has been updated for clarity.
* False claims about :meth:`iris.fileformats.pp.save`, :meth:`iris.fileformats.pp.as_pairs`, and :meth:`iris.fileformats.pp.as_fields` being able to take instances of :class:`iris.cube.CubeList` as inputs have been removed.
-* A :doc:`new code example <../examples/Meteorology/wind_speed>`, demonstrating the use of a quiver plot to display wind speeds over Lake Victoria, has been added.
+* A new code example :ref:`sphx_glr_generated_gallery_meteorology_plot_wind_speed.py`, demonstrating the use of a quiver plot to display wind speeds over Lake Victoria, has been added.
* The docstring for :data:`iris.analysis.SUM` has been updated to explicitly state that weights passed to it aren't normalised internally.
* A note regarding the impossibility of partially collapsing multi-dimensional coordinates has been added to the user guide.
diff --git a/docs/iris/src/whatsnew/1.11.rst b/docs/iris/src/whatsnew/1.11.rst
index eb93ec2f8c..560bb07032 100644
--- a/docs/iris/src/whatsnew/1.11.rst
+++ b/docs/iris/src/whatsnew/1.11.rst
@@ -1,4 +1,4 @@
-What's New in Iris 1.11
+What's new in Iris 1.11
***********************
:Release: 1.11
@@ -7,14 +7,14 @@ What's New in Iris 1.11
This document explains the new/changed features of Iris in version 1.11
(:doc:`View all changes `.)
-Iris 1.11 Features
+Iris 1.11 features
==================
* If available, display the ``STASH`` code instead of ``unknown / (unknown)`` when printing cubes
with no ``standard_name`` and no ``units``.
* Support for saving to netCDF with data packing has been added.
* The coordinate system :class:`iris.coord_systems.LambertAzimuthalEqualArea` has been added with NetCDF saving support.
-Bugs Fixed
+Bugs fixed
==========
* Fixed a floating point tolerance bug in :func:`iris.experimental.regrid.regrid_area_weighted_rectilinear_src_and_grid`
for wrapped longitudes.
@@ -25,7 +25,7 @@ Bugs Fixed
* When saving to NetCDF, the existing behaviour of writing string attributes as ASCII has been
maintained across known versions of netCDF4-python.
-Documentation Changes
+Documentation changes
=====================
* Fuller doc-string detail added to :func:`iris.analysis.cartography.unrotate_pole` and
:func:`iris.analysis.cartography.rotate_pole`.
diff --git a/docs/iris/src/whatsnew/1.12.rst b/docs/iris/src/whatsnew/1.12.rst
index 59ea47d876..bd02f0937a 100644
--- a/docs/iris/src/whatsnew/1.12.rst
+++ b/docs/iris/src/whatsnew/1.12.rst
@@ -1,4 +1,4 @@
-What's New in Iris 1.12
+What's new in Iris 1.12
***********************
:Release: 1.12
@@ -7,7 +7,7 @@ What's New in Iris 1.12
This document explains the new/changed features of Iris in version 1.12
(:doc:`View all changes `.)
-Iris 1.12 Features
+Iris 1.12 features
==================
.. _showcase:
@@ -125,7 +125,7 @@ Deprecations
of the new fast-loading mechanism provided by
:meth:`iris.fileformats.um.structured_um_loading`.
-Documentation Changes
+Documentation changes
=====================
* Corrected documentation of :class:`iris.analysis.AreaWeighted` scheme to make
the usage scope clearer.
diff --git a/docs/iris/src/whatsnew/1.13.rst b/docs/iris/src/whatsnew/1.13.rst
index 532c160f13..7435e5bb07 100644
--- a/docs/iris/src/whatsnew/1.13.rst
+++ b/docs/iris/src/whatsnew/1.13.rst
@@ -1,4 +1,4 @@
-What's New in Iris 1.13
+What's new in Iris 1.13
***********************
:Release: 1.13
@@ -8,7 +8,7 @@ What's New in Iris 1.13
This document explains the new/changed features of Iris in version 1.13
(:doc:`View all changes `.)
-Iris 1.13 Features
+Iris 1.13 features
==================
* Allow the reading of NAME trajectories stored by time instead of by particle number.
@@ -16,7 +16,7 @@ Iris 1.13 Features
* Data arrays may be shared between cubes, and subsets of cubes, by using the :meth:`iris.cube.share_data` flag.
-Bug Fixes
+Bug fixes
=========
* The bounds are now set correctly on the longitude coordinate if a zonal mean diagnostic has been loaded from a PP file as per the CF Standard.
diff --git a/docs/iris/src/whatsnew/1.4.rst b/docs/iris/src/whatsnew/1.4.rst
index 053a6e1096..3586b05a5c 100644
--- a/docs/iris/src/whatsnew/1.4.rst
+++ b/docs/iris/src/whatsnew/1.4.rst
@@ -105,8 +105,8 @@ Iris-Pandas interoperablilty
Conversion to and from Pandas Series_ and DataFrames_ is now available.
See :mod:`iris.pandas` for more details.
-.. _Series: http://pandas.pydata.org/pandas-docs/stable/api.html#series
-.. _DataFrames: http://pandas.pydata.org/pandas-docs/stable/api.html#dataframe
+.. _Series: https://pandas.pydata.org/pandas-docs/stable/reference/series.html
+.. _DataFrames: https://pandas.pydata.org/pandas-docs/stable/reference/frame.html
.. _load-opendap:
diff --git a/docs/iris/src/whatsnew/1.5.rst b/docs/iris/src/whatsnew/1.5.rst
index 7af1e40285..6a4f418259 100644
--- a/docs/iris/src/whatsnew/1.5.rst
+++ b/docs/iris/src/whatsnew/1.5.rst
@@ -101,7 +101,7 @@ Iris 1.5 features
the direction of vertical axes will be reversed if the corresponding
coordinate has a "positive" attribute set to "down".
- see: :ref:`Oceanography-atlantic_profiles`
+ see: :ref:`sphx_glr_generated_gallery_oceanography_plot_atlantic_profiles.py`
* New PP stashcode translations added including 'dewpoint' and
'relative_humidity'.
diff --git a/docs/iris/src/whatsnew/1.7.rst b/docs/iris/src/whatsnew/1.7.rst
index 2f3a52fbb9..2d4395239b 100644
--- a/docs/iris/src/whatsnew/1.7.rst
+++ b/docs/iris/src/whatsnew/1.7.rst
@@ -229,20 +229,19 @@ Deprecations
:func:`iris.fileformats.grib.reset_load_rules` functions.
* Matplotlib is no longer a core Iris dependency.
-Documentation Changes
+Documentation changes
=====================
* New sections on :ref:`cube broadcasting ` and
:doc:`regridding and interpolation `
have been added to the :doc:`user guide `.
* An example demonstrating custom log-scale colouring has been added.
- See :ref:`General-anomaly_log_colouring`.
+ See :ref:`sphx_glr_generated_gallery_general_plot_anomaly_log_colouring.py`.
* An example demonstrating the creation of a custom
:class:`iris.analysis.Aggregator` has been added.
- See :ref:`General-custom_aggregation`.
+ See :ref:`sphx_glr_generated_gallery_general_plot_custom_aggregation.py`.
* An example of reprojecting data from 2D auxiliary spatial coordinates
- (such as that from the ORCA grid) has been added. See :ref:`General-orca_projection`.
+ (such as that from the ORCA grid) has been added. See :ref:`sphx_glr_generated_gallery_general_plot_orca_projection.py`.
* A clarification of the behaviour of :func:`iris.analysis.calculus.differentiate`.
-* A new :doc:`"whitepapers" ` section has been added to the documentation along
+* A new :doc:`"Technical Papers" ` section has been added to the documentation along
with the addition of a paper providing an :doc:`overview of the load process for UM-like
- fileformats (e.g. PP and Fieldsfile) `.
-
+ fileformats (e.g. PP and Fieldsfile) `.
diff --git a/docs/iris/src/whatsnew/1.8.rst b/docs/iris/src/whatsnew/1.8.rst
index c763411ed8..54763a194b 100644
--- a/docs/iris/src/whatsnew/1.8.rst
+++ b/docs/iris/src/whatsnew/1.8.rst
@@ -169,7 +169,7 @@ Deprecations
"iris.experimental.regrid.regrid_bilinear_rectilinear_src_and_grid" has been removed, as
:class:`iris.analysis.Linear` now includes this functionality.
-Documentation Changes
+Documentation changes
=====================
* A chapter on :doc:`merge and concatenate ` has been
added to the :doc:`user guide `.
diff --git a/docs/iris/src/whatsnew/1.9.rst b/docs/iris/src/whatsnew/1.9.rst
index 7a4848b434..7fda661ebc 100644
--- a/docs/iris/src/whatsnew/1.9.rst
+++ b/docs/iris/src/whatsnew/1.9.rst
@@ -1,4 +1,4 @@
-What's New in Iris 1.9
+What's new in Iris 1.9
**********************
:Release: 1.9.2
@@ -7,7 +7,7 @@ What's New in Iris 1.9
This document explains the new/changed features of Iris in version 1.9
(:doc:`View all changes `.)
-Iris 1.9 Features
+Iris 1.9 features
=================
* Support for running on Python 3.4 has been added to the whole code base. Some features which
depend on external libraries will not be available until they also support Python 3, namely:
@@ -66,7 +66,7 @@ Iris 1.9 Features
* The :meth:`iris.experimental.um.Field.get_data` method can now be used to read Fieldsfile data
after the original :class:`iris.experimental.um.FieldsFileVariant` has been closed.
-Bugs Fixed
+Bugs fixed
==========
* Fixed a bug in :meth:`iris.unit.Unit.convert`
(and the equivalent in `cf_units `_)
@@ -109,7 +109,7 @@ Version 1.9.2
* Fixed a bug avoiding sorting classes directly when :meth:`iris.cube.Cube.coord_system` is used in Python3.
* Fixed a bug regarding unsuccessful dot import.
-Incompatible Changes
+Incompatible changes
====================
* GRIB message/file reading and writing may not be available for Python 3 due to GRIB API limitations.
@@ -121,7 +121,7 @@ Deprecations
but it is *not* set.
* Deprecated :class:`iris.aux_factory.LazyArray`
-Documentation Changes
+Documentation changes
=====================
* A chapter on :doc:`saving iris cubes ` has been
added to the :doc:`user guide `.
diff --git a/docs/iris/src/whatsnew/2.0.rst b/docs/iris/src/whatsnew/2.0.rst
index 43d60a8539..61568d3a8e 100644
--- a/docs/iris/src/whatsnew/2.0.rst
+++ b/docs/iris/src/whatsnew/2.0.rst
@@ -1,4 +1,4 @@
-What's New in Iris 2.0.0
+What's new in Iris 2.0.0
************************
:Release: 2.0.0rc1
@@ -9,7 +9,7 @@ This document explains the new/changed features of Iris in version 2.0.0
(:doc:`View all changes `).
-Iris 2.0.0 Features
+Iris 2.0.0 features
===================
.. _showcase:
@@ -114,7 +114,7 @@ all existing toggles in :attr:`iris.FUTURE` now default to :data:`True`.
off is now deprecated.
-Bugs Fixed
+Bugs fixed
==========
* Indexing or slicing an :class:`~iris.coords.AuxCoord` coordinate will return a coordinate with
@@ -289,7 +289,7 @@ been removed. In particular:
removed from the :class:`iris.fileformats.rules.Loader` constructor.
-Documentation Changes
+Documentation changes
=====================
* A new UserGuide chapter on :doc:`Real and Lazy Data
diff --git a/docs/iris/src/whatsnew/2.1.rst b/docs/iris/src/whatsnew/2.1.rst
index 00f7115431..a82d3b8470 100644
--- a/docs/iris/src/whatsnew/2.1.rst
+++ b/docs/iris/src/whatsnew/2.1.rst
@@ -1,4 +1,4 @@
-What's New in Iris 2.1
+What's new in Iris 2.1
**********************
:Release: 2.1
@@ -8,7 +8,7 @@ This document explains the new/changed features of Iris in version 2.1
(:doc:`older "What's New" release notes can be found here`.)
-Iris 2.1 Dependency updates
+Iris 2.1 dependency updates
===========================
* The `cf_units `_ dependency
@@ -30,7 +30,7 @@ Iris 2.1 Dependency updates
Full requirements can be seen in the `requirements `_
directory of the Iris' the source.
-Iris 2.1 Features
+Iris 2.1 features
=================
* Added ``repr_html`` functionality to the :class:`~iris.cube.Cube` to provide
@@ -60,7 +60,7 @@ Iris 2.1 Features
* The :class:`~iris.coord_systems.Mercator` projection has been updated to accept
the ``standard_parallel`` keyword argument (:pull:`3041`).
-Bugs Fixed
+Bugs fixed
==========
* All var names being written to NetCDF are now CF compliant.
@@ -73,7 +73,7 @@ Bugs Fixed
* :mod:`iris.quickplot` labels now honour the axes being drawn to when using the
``axes`` keyword (:pull:`3010`).
-Incompatible Changes
+Incompatible changes
====================
* The deprecated :mod:`iris.experimental.um` was removed.
Please use consider using `mule `_
diff --git a/docs/iris/src/whatsnew/2.2.rst b/docs/iris/src/whatsnew/2.2.rst
index 1eff99ecb4..75be5460b3 100644
--- a/docs/iris/src/whatsnew/2.2.rst
+++ b/docs/iris/src/whatsnew/2.2.rst
@@ -1,4 +1,4 @@
-What's New in Iris 2.2
+What's new in Iris 2.2
************************
:Release: 2.2.0
@@ -10,7 +10,7 @@ of version 2.2
(:doc:`View all changes `).
-Iris 2.2 Features
+Iris 2.2 features
===================
.. _showcase:
@@ -70,7 +70,7 @@ Iris 2.2 Features
a NaN-tolerant array comparison.
-Iris 2.2 Dependency updates
+Iris 2.2 dependency updates
=============================
* Iris is now using the latest version release of dask (currently 0.19.3)
@@ -82,7 +82,7 @@ Iris 2.2 Dependency updates
its changes in all SciTools libraries.
-Bugs Fixed
+Bugs fixed
==========
* The bug has been fixed that prevented printing time coordinates with bounds
@@ -109,7 +109,7 @@ Bugs fixed in v2.2.1
-Documentation Changes
+Documentation changes
=====================
* Iris' `INSTALL` document has been updated to include guidance for running
diff --git a/docs/iris/src/whatsnew/2.3.rst b/docs/iris/src/whatsnew/2.3.rst
index 872fb44cd6..6fb7088339 100644
--- a/docs/iris/src/whatsnew/2.3.rst
+++ b/docs/iris/src/whatsnew/2.3.rst
@@ -1,4 +1,4 @@
-What's New in Iris 2.3.0
+What's new in Iris 2.3.0
************************
:Release: 2.3.0
@@ -7,7 +7,7 @@ What's New in Iris 2.3.0
This document explains the new/changed features of Iris in version 2.3.0
(:doc:`View all changes `.)
-Iris 2.3.0 Features
+Iris 2.3.0 features
===================
.. _showcase:
@@ -103,12 +103,12 @@ Iris 2.3.0 Features
relaxed
tolerance : This means that some cubes may now test 'equal' that previously
did not.
- Previously, Iris compared cube data arrays using:
- ``abs(a - b) < 1.e-8``
+ Previously, Iris compared cube data arrays using
+ ``abs(a - b) < 1.e-8``
We now apply the default operation of :func:`numpy.allclose` instead,
- which is equivalent to:
- ``abs(a - b) < (1.e-8 + 1.e-5 * b)``
+ which is equivalent to
+ ``abs(a - b) < (1.e-8 + 1.e-5 * b)``
* Added support to render HTML for :class:`~iris.cube.CubeList` in Jupyter
Notebooks and JupyterLab.
@@ -135,7 +135,7 @@ Iris 2.3.0 Features
`metarelate/metOcean commit 448f2ef, 2019-11-29 `_
-Iris 2.3.0 Dependency Updates
+Iris 2.3.0 dependency updates
=============================
* Iris now supports Proj4 up to version 5, but not yet 6 or beyond, pending
`fixes to some cartopy tests `_; had been
erroneously using Geostationary.
-* :class:`~iris.coords.CellMethod` will now only use valid `NetCDF name tokens `_ to reference the coordinates involved in the statistical operation.
-* The following var_name properties will now only allow valid `NetCDF name
- tokens
- `_ to
- reference the said NetCDF variable name. Note that names with a leading
+* :class:`~iris.coords.CellMethod` will now only use valid `NetCDF name tokens`_ to reference the coordinates involved in the statistical operation.
+* The following var_name properties will now only allow valid
+ `NetCDF name tokens`_
+ to reference the said NetCDF variable name. Note that names with a leading
underscore are not permitted.
- - :attr:`iris.aux_factory.AuxCoordFactory.var_name`
- - :attr:`iris.coords.CellMeasure.var_name`
- - :attr:`iris.coords.Coord.var_name`
- - :attr:`iris.coords.AuxCoord.var_name`
- - :attr:`iris.cube.Cube.var_name`
+
+.. _NetCDF name tokens: https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/netcdf_data_set_components.html#object_name
+
+ * :attr:`iris.aux_factory.AuxCoordFactory.var_name`
+ * :attr:`iris.coords.CellMeasure.var_name`
+ * :attr:`iris.coords.Coord.var_name`
+ * :attr:`iris.coords.AuxCoord.var_name`
+ * :attr:`iris.cube.Cube.var_name`
+
* Rendering a cube in Jupyter will no longer crash for a cube with
attributes containing ``\n``.
* NetCDF variables which reference themselves in their ``cell_measures``
@@ -199,12 +201,12 @@ Bugs Fixed
the original attached AuxCoords.
-Documentation Changes
+Documentation changes
=====================
* Adopted a
`new colour logo for Iris <../_static/Iris7_1_trim_full.png>`_
-* Added a gallery example showing `how to concatenate NEMO ocean model data
- <../examples/Oceanography/load_nemo.html>`_.
+* Added a gallery example showing how to concatenate NEMO ocean model data,
+ see :ref:`sphx_glr_generated_gallery_oceanography_plot_load_nemo.py`.
* Added an example in the
`Loading Iris Cubes: Constraining on Time <../userguide/loading_iris_cubes
.html#constraining-on-time>`_
diff --git a/docs/iris/src/whatsnew/2.4.rst b/docs/iris/src/whatsnew/2.4.rst
index 2facb97a7a..776cc8aa69 100644
--- a/docs/iris/src/whatsnew/2.4.rst
+++ b/docs/iris/src/whatsnew/2.4.rst
@@ -1,4 +1,4 @@
-What's New in Iris 2.4.0
+What's new in Iris 2.4.0
************************
:Release: 2.4.0
@@ -8,7 +8,7 @@ This document explains the new/changed features of Iris in version 2.4.0
(:doc:`View all changes `.)
-Iris 2.4.0 Features
+Iris 2.4.0 features
===================
.. admonition:: Last python 2 version of Iris
@@ -44,12 +44,12 @@ Iris 2.4.0 Features
from the attributes dictionary of a :class:`~iris.cube.Cube`.
-Iris 2.4.0 Dependency Updates
+Iris 2.4.0 dependency updates
=============================
* Iris is now able to use the latest version of matplotlib.
-Bugs Fixed
+Bugs fixed
==========
* Fixed a problem which was causing file loads to fetch *all* field data
whenever UM files (PP or Fieldsfiles) were loaded.
diff --git a/docs/iris/src/whatsnew/aggregate_directory.py b/docs/iris/src/whatsnew/aggregate_directory.py
index c7b497307f..6fe92f6764 100644
--- a/docs/iris/src/whatsnew/aggregate_directory.py
+++ b/docs/iris/src/whatsnew/aggregate_directory.py
@@ -42,7 +42,7 @@
SOFTWARE_NAME = "Iris"
EXTENSION = ".rst"
VALID_CATEGORIES = [
- {"Prefix": "newfeature", "Title": "Features"},
+ {"Prefix": "newfeature", "Title": "features"},
{"Prefix": "bugfix", "Title": "Bugs Fixed"},
{"Prefix": "incompatiblechange", "Title": "Incompatible Changes"},
{"Prefix": "deprecate", "Title": "Deprecations"},
@@ -165,7 +165,7 @@ def generate_header(release, unreleased=False):
else:
isodatestamp = datetime.date.today().strftime("%Y-%m-%d")
header_text = []
- title_template = "What's New in {} {!s}\n"
+ title_template = "What's new in {} {!s}\n"
title_line = title_template.format(SOFTWARE_NAME, release)
title_underline = ("*" * (len(title_line) - 1)) + "\n"
header_text.append(title_line)
diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Jul-10_modernise_documentation_using_themes_and_readthedocs.txt b/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Jul-10_modernise_documentation_using_themes_and_readthedocs.txt
new file mode 100644
index 0000000000..5ff8c001e8
--- /dev/null
+++ b/docs/iris/src/whatsnew/contributions_3.0.0/docchange_2020-Jul-10_modernise_documentation_using_themes_and_readthedocs.txt
@@ -0,0 +1,2 @@
+* Updated documentation to use a modern sphinx theme and be served from
+ https://scitools-iris.readthedocs.io/en/latest/.
diff --git a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-Jan-31_nimrod_format_enhancement.txt b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-Jan-31_nimrod_format_enhancement.txt
index 454fc3617f..18378691cb 100644
--- a/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-Jan-31_nimrod_format_enhancement.txt
+++ b/docs/iris/src/whatsnew/contributions_3.0.0/newfeature_2020-Jan-31_nimrod_format_enhancement.txt
@@ -1,3 +1,3 @@
* The :class:`~iris.fileformats.nimrod` provides richer meta-data translation
-when loading Nimrod-format data into cubes. This covers most known operational
-use-cases.
+ when loading Nimrod-format data into cubes. This covers most known operational
+ use-cases.
diff --git a/docs/iris/src/whatsnew/index.rst b/docs/iris/src/whatsnew/index.rst
index 03834a43a7..00b925a48e 100644
--- a/docs/iris/src/whatsnew/index.rst
+++ b/docs/iris/src/whatsnew/index.rst
@@ -7,10 +7,10 @@ These "What's new" pages describe the important changes between major
Iris versions.
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
latest.rst
- 3.0.rst
+ 3.0.0.rst
2.4.rst
2.3.rst
2.2.rst
diff --git a/lib/iris/_constraints.py b/lib/iris/_constraints.py
index 37daeec4aa..4746425bb3 100644
--- a/lib/iris/_constraints.py
+++ b/lib/iris/_constraints.py
@@ -515,6 +515,7 @@ def __init__(
match.
Kwargs:
+
* standard_name:
A string or callable representing the standard name to match
against.
@@ -534,6 +535,7 @@ def __init__(
where the standard_name is not set, then use standard_name=None.
Returns:
+
* Boolean
Example usage::
@@ -544,8 +546,8 @@ def __init__(
iris.NameConstraint(standard_name='air_temperature',
STASH=lambda stash: stash.item == 203)
-
"""
+
self.standard_name = standard_name
self.long_name = long_name
self.var_name = var_name
diff --git a/lib/iris/analysis/__init__.py b/lib/iris/analysis/__init__.py
index 5b7dff813d..0d4d3bfdab 100644
--- a/lib/iris/analysis/__init__.py
+++ b/lib/iris/analysis/__init__.py
@@ -27,11 +27,11 @@
The gallery contains several interesting worked examples of how an
:class:`~iris.analysis.Aggregator` may be used, including:
- * :ref:`Meteorology-COP_1d_plot`
- * :ref:`General-SOI_filtering`
- * :ref:`Meteorology-hovmoller`
- * :ref:`Meteorology-lagged_ensemble`
- * :ref:`General-custom_aggregation`
+ * :ref:`sphx_glr_generated_gallery_meteorology_plot_COP_1d.py`
+ * :ref:`sphx_glr_generated_gallery_general_plot_SOI_filtering.py`
+ * :ref:`sphx_glr_generated_gallery_meteorology_plot_hovmoller.py`
+ * :ref:`sphx_glr_generated_gallery_meteorology_plot_lagged_ensemble.py`
+ * :ref:`sphx_glr_generated_gallery_general_plot_custom_aggregation.py`
"""
@@ -487,7 +487,8 @@ def __init__(
A variety of ready-made aggregators are provided in this module, such
as :data:`~iris.analysis.MEAN` and :data:`~iris.analysis.MAX`. Custom
aggregators can also be created for special purposes, see
- :ref:`General-custom_aggregation` for a worked example.
+ :ref:`sphx_glr_generated_gallery_general_plot_custom_aggregation.py`
+ for a worked example.
"""
#: Cube cell method string.
diff --git a/lib/iris/analysis/stats.py b/lib/iris/analysis/stats.py
index ba3ed2504c..bb283a0e89 100644
--- a/lib/iris/analysis/stats.py
+++ b/lib/iris/analysis/stats.py
@@ -64,7 +64,7 @@ def pearsonr(
correlation at each time/altitude point.
Reference:
- http://www.statsoft.com/textbook/glosp.html#Pearson%20Correlation
+ https://en.wikipedia.org/wiki/Pearson_correlation_coefficient
This operation is non-lazy.
diff --git a/lib/iris/cube.py b/lib/iris/cube.py
index 03e942c6c9..964e56c313 100644
--- a/lib/iris/cube.py
+++ b/lib/iris/cube.py
@@ -1200,6 +1200,7 @@ def add_ancillary_variable(self, ancillary_variable, data_dims=None):
the cube
Kwargs:
+
* data_dims
Integer or iterable of integers giving the data dimensions spanned
by the ancillary variable.
@@ -1207,6 +1208,7 @@ def add_ancillary_variable(self, ancillary_variable, data_dims=None):
Raises a ValueError if an ancillary variable with identical metadata
already exists on the cube.
"""
+
if self.ancillary_variables(ancillary_variable):
raise ValueError("Duplicate ancillary variables not permitted")
diff --git a/lib/iris/experimental/stratify.py b/lib/iris/experimental/stratify.py
index 2992360247..e357f2ca9d 100644
--- a/lib/iris/experimental/stratify.py
+++ b/lib/iris/experimental/stratify.py
@@ -68,8 +68,8 @@ def relevel(cube, src_levels, tgt_levels, axis=None, interpolator=None):
that are generally monotonic in the direction of interpolation, such as
height/pressure or salinity/depth.
- Parameters
- ----------
+ Args:
+
cube : :class:`~iris.cube.Cube`
The phenomenon data to be re-levelled.
diff --git a/lib/iris/fileformats/cf.py b/lib/iris/fileformats/cf.py
index 1db4e6c61e..75f328a80e 100644
--- a/lib/iris/fileformats/cf.py
+++ b/lib/iris/fileformats/cf.py
@@ -10,7 +10,7 @@
References:
[CF] NetCDF Climate and Forecast (CF) Metadata conventions, Version 1.5, October, 2010.
-[NUG] NetCDF User's Guide, http://www.unidata.ucar.edu/software/netcdf/docs/netcdf.html
+[NUG] NetCDF User's Guide, https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/
"""
diff --git a/lib/iris/fileformats/netcdf.py b/lib/iris/fileformats/netcdf.py
index 4d7ddedc61..867b0c9faf 100644
--- a/lib/iris/fileformats/netcdf.py
+++ b/lib/iris/fileformats/netcdf.py
@@ -959,7 +959,7 @@ def write(
than global attributes.
* unlimited_dimensions (iterable of strings and/or
- :class:`iris.coords.Coord` objects):
+ :class:`iris.coords.Coord` objects):
List of coordinate names (or coordinate objects)
corresponding to coordinate dimensions of `cube` to save with the
NetCDF dimension variable length 'UNLIMITED'. By default, no
@@ -992,10 +992,10 @@ def write(
Used to manually specify the HDF5 chunksizes for each dimension of
the variable. A detailed discussion of HDF chunking and I/O
performance is available here:
- http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html. Basically,
- you want the chunk size for each dimension to match as closely as
- possible the size of the data block that users will read from the
- file. `chunksizes` cannot be set if `contiguous=True`.
+ https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/netcdf_perf_chunking.html.
+ Basically, you want the chunk size for each dimension to match
+ as closely as possible the size of the data block that users will
+ read from the file. `chunksizes` cannot be set if `contiguous=True`.
* endian (string):
Used to control whether the data is stored in little or big endian
@@ -2506,7 +2506,7 @@ def save(
than global attributes.
* unlimited_dimensions (iterable of strings and/or
- :class:`iris.coords.Coord` objects):
+ :class:`iris.coords.Coord` objects):
List of coordinate names (or coordinate objects) corresponding
to coordinate dimensions of `cube` to save with the NetCDF dimension
variable length 'UNLIMITED'. By default, no unlimited dimensions are
@@ -2538,7 +2538,7 @@ def save(
* chunksizes (tuple of int):
Used to manually specify the HDF5 chunksizes for each dimension of the
variable. A detailed discussion of HDF chunking and I/O performance is
- available here: http://www.hdfgroup.org/HDF5/doc/H5.user/Chunking.html.
+ available here: https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/netcdf_perf_chunking.html.
Basically, you want the chunk size for each dimension to match as
closely as possible the size of the data block that users will read
from the file. `chunksizes` cannot be set if `contiguous=True`.
diff --git a/lib/iris/tests/__init__.py b/lib/iris/tests/__init__.py
index 8602defa16..9132e16680 100644
--- a/lib/iris/tests/__init__.py
+++ b/lib/iris/tests/__init__.py
@@ -792,7 +792,7 @@ def _unique_id(self):
bits[0] = os.path.splitext(file_name)[0]
folder, location = os.path.split(path)
bits = [location] + bits
- while location not in ["iris", "example_tests"]:
+ while location not in ["iris", "gallery_tests"]:
folder, location = os.path.split(folder)
bits = [location] + bits
test_id = ".".join(bits)
diff --git a/lib/iris/tests/results/imagerepo.json b/lib/iris/tests/results/imagerepo.json
index e6a225f022..a353507d12 100644
--- a/lib/iris/tests/results/imagerepo.json
+++ b/lib/iris/tests/results/imagerepo.json
@@ -1,129 +1,129 @@
{
- "example_tests.test_COP_1d_plot.TestCOP1DPlot.test_COP_1d_plot.0": [
+ "gallery_tests.test_plot_COP_1d.TestCOP1DPlot.test_plot_COP_1d.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/baff589936602d8ec977334ae4dac9b61a6dc4d99532c86cc2913e36c4cc0f61.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/aefec91c3601249cc9b3336dc4c8cdb31a64c6d997b3c0eccb5932d285e42f33.png"
],
- "example_tests.test_COP_maps.TestCOPMaps.test_cop_maps.0": [
+ "gallery_tests.test_plot_COP_maps.TestCOPMaps.test_plot_cop_maps.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/ea9138db95668524913e6ac168997e85957e917e876396b96a81b5ce3c496935.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ea9130db95668524913c6ac178995b0d956e917ec76396b96a853dcf94696935.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ea9130db95668524913e6ac168991f0d956e917ec76396b96a853dcf94796931.png"
],
- "example_tests.test_SOI_filtering.TestSOIFiltering.test_soi_filtering.0": [
+ "gallery_tests.test_plot_SOI_filtering.TestSOIFiltering.test_plot_soi_filtering.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/fac460b9c17b78723e05a5a9954edaf062332799954e9ca5c63b9a52d24e5a95.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fa8460b9c17b78723e05a5a9954edaf062333799954e9ca5c63b9a52d24e4a9d.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fa167295c5e0696a3c17a58c9568da536233da19994cdab487739b4b9b444eb5.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fa56f295c5e0694a3c17a58d95e8da536233da99984c5af4c6739b4a9a444eb4.png"
],
- "example_tests.test_TEC.TestTEC.test_TEC.0": [
+ "gallery_tests.test_plot_TEC.TestTEC.test_plot_TEC.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/e1a561b69b1a9a42846e9a49c7596e3cce6c907b3a83c17e1b8239b3e4f33bc4.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e1a561b69b1a9e43846e9a49c7596e2cce6c907b3a83c16e1b9231b3e4f33b8c.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e5a761b69a589a4bc46f9e48c65c6631ce61d1ce3982c13739b33193c0ee3f8c.png"
],
- "example_tests.test_anomaly_log_colouring.TestAnomalyLogColouring.test_anomaly_log_colouring.0": [
+ "gallery_tests.test_plot_anomaly_log_colouring.TestAnomalyLogColouring.test_plot_anomaly_log_colouring.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/ec4464e185a39f93931e9b1e91696d2949dde6e63e26a47a5ad391938d9a5a0c.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ecc164e78e979b19b3789b0885a564a56cc2c65e3ec69469db1bdb9a853c1e24.png"
],
- "example_tests.test_atlantic_profiles.TestAtlanticProfiles.test_atlantic_profiles.0": [
+ "gallery_tests.test_plot_atlantic_profiles.TestAtlanticProfiles.test_plot_atlantic_profiles.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/9f8260536bd28e1320739437b5f437b0a51d66f4cc5d08fcd00fdb1c93fcb21c.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/9f8260536bd28e1320739437b5f437b0a51d66f4cc7c09f4d00fdb1c93fcb21c.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/9f8a60536bd28e1320739437b5f437b0a53d66f4cc5c08f4d00fdb1c93fcb21c.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/9fc060f462a08f07203ebc77a1f36707e61f4e38d8f7d08a910197fc877cec58.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/97c160f462a88f07203ebc77a1e36707e61f4e38d8f3d08a910597fc877cec58.png"
],
- "example_tests.test_atlantic_profiles.TestAtlanticProfiles.test_atlantic_profiles.1": [
+ "gallery_tests.test_plot_atlantic_profiles.TestAtlanticProfiles.test_plot_atlantic_profiles.1": [
"https://scitools.github.io/test-iris-imagehash/images/v4/a6eaa57e6e81ddf999311ba3b3775e20845d5889c199673b4e22a4675e8ca11c.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/eeea64dd6ea8cd99991f1322b3761e06845718d89995b3131f32a4765ec2a1cd.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/eeea64dd6ea8cd99991d1322b3741e2684571cd89995b3131f32a4765ee2a1cc.png"
],
- "example_tests.test_coriolis_plot.TestCoriolisPlot.test_coriolis_plot.0": [
+ "gallery_tests.test_plot_coriolis.TestCoriolisPlot.test_plot_coriolis.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/e78665de9a699659e55e9965886979966986c5e63e98c19e3a256679e1981a24.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e68665de9a699659c1fe99a5896965966996c46e3e19c1da3a652669c51e1a26.png"
],
- "example_tests.test_cross_section.TestCrossSection.test_cross_section.0": [
+ "gallery_tests.test_plot_cross_section.TestCrossSection.test_plot_cross_section.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/ea95317b9562e4d1649f5a05856e4ca4da52947e4ea5f13f1b499d42f13b1b41.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ea91b17b9562e4d1609f5a05856e4ca45a52957e5ea5f13b1bca9dc0b17b1ac1.png"
],
- "example_tests.test_cross_section.TestCrossSection.test_cross_section.1": [
+ "gallery_tests.test_plot_cross_section.TestCrossSection.test_plot_cross_section.1": [
"https://scitools.github.io/test-iris-imagehash/images/v4/ea9521fb956a394069921e93f07f4aad856cc47e4e95857a1ea5da3591ba1b81.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ea9521fb956a394068931e9be07e4aa5856cc47e4a91957a1ba55bb5b17a3b81.png"
],
- "example_tests.test_custom_aggregation.TestCustomAggregation.test_custom_aggregation.0": [
+ "gallery_tests.test_plot_custom_aggregation.TestCustomAggregation.test_plot_custom_aggregation.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/fe816e81917e907eb43e873f85677ac190f0703c6a95811f1ac33ce1a57a6f18.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fe816e81817e907eb43e873f85637ac198d8703c6a94811f1ac73ee1a57a6f90.png"
],
- "example_tests.test_custom_file_loading.TestCustomFileLoading.test_custom_file_loading.0": [
+ "gallery_tests.test_plot_custom_file_loading.TestCustomFileLoading.test_plot_custom_file_loading.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/faa0cbf1845e34be913787416edcc8bc3bc81f9b63332662a4ed30cdc1b2cd21.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fba0cbf1845e34be912787416edcc8bc3b881f9b62332762a5ad32cdc1b2cd21.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/faa1cb47845e34bc912797436cccc8343f11359b73523746c48c72d9d9b34da5.png"
],
- "example_tests.test_deriving_phenomena.TestDerivingPhenomena.test_deriving_phenomena.0": [
+ "gallery_tests.test_plot_deriving_phenomena.TestDerivingPhenomena.test_plot_deriving_phenomena.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/b9993986866952e6c9464639c4766bd9c669916e7b99c1663f99768990763e81.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/b99139de866952e6c946c639c47e6bd18769d16e7a9981662e813699d0763e89.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ec97681793689768943c97e8926669d186e8c33f6c99c32e6b936c83d33e2c98.png"
],
- "example_tests.test_global_map.TestGlobalMap.test_global_map.0": [
+ "gallery_tests.test_plot_global_map.TestGlobalMap.test_plot_global_map.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/fa9979468566857ef07e3e8978566b91cb0179883c89946686a96b9d83766f81.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fa997b958466846ed13e87467a997a898d66d17e2cc9906684696f99d3162f81.png"
],
- "example_tests.test_hovmoller.TestGlobalMap.test_hovmoller.0": [
+ "gallery_tests.test_plot_hovmoller.TestGlobalMap.test_plot_hovmoller.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/bab430b4ce4bce43c5becf89c54b1a63c543c56e1e64907e3bb469b490de1ac1.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/eeb46cb4934b934bc07e974bc14b38949943c0fe3e94c17f6ea46cb4c07b3f00.png"
],
- "example_tests.test_inset_plot.TestInsetPlot.test_inset_plot.0": [
+ "gallery_tests.test_plot_inset.TestInsetPlot.test_plot_inset.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/ebff6992f50096a5b245dac4f6559496b49248dbc95dcb699529912dcf244a54.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e9ff6992b50096a5b245dac4f64594b6b49248dbc95dcb699529952dcf244a56.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ebff6992b50096ad9267dac4d64094b294924cdbc95d4b699d29952dcda46e94.png"
],
- "example_tests.test_lagged_ensemble.TestLaggedEnsemble.test_lagged_ensemble.0": [
+ "gallery_tests.test_plot_lagged_ensemble.TestLaggedEnsemble.test_plot_lagged_ensemble.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/bbbb31e1c44e64e4b0459b5bb1716ecac464f496ce34618eb1079b39b193ce25.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/bbbb31b1c44e64e4b1579b5b917133cecc61f146c414668eb1119b1bb197ce34.png"
],
- "example_tests.test_lagged_ensemble.TestLaggedEnsemble.test_lagged_ensemble.1": [
+ "gallery_tests.test_plot_lagged_ensemble.TestLaggedEnsemble.test_plot_lagged_ensemble.1": [
"https://scitools.github.io/test-iris-imagehash/images/v4/abfef958fd462c993a07d87960464b81d1009687c139d3b594e9cf87c6b89687.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/aafec5e9e5e03e099a07e0f86542db879438261ec3b13ce78d8dc65a92d83d89.png"
],
- "example_tests.test_lineplot_with_legend.TestLineplotWithLegend.test_lineplot_with_legend.0": [
+ "gallery_tests.test_plot_lineplot_with_legend.TestLineplotWithLegend.test_plot_lineplot_with_legend.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/eae942526540b869961f8da694589da69543cc9af1014afbc3fd596b84fe19a7.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/eae942146540b869961f8de694589da69543cc9af1014afbc3fd596b84fe19a7.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/eafd9e12a5a061e9925ec716de489e9685078ec981b229e70ddb79219cc3768d.png"
],
- "example_tests.test_load_nemo.TestLoadNemo.test_load_nemo.0": [
+ "gallery_tests.test_plot_load_nemo.TestLoadNemo.test_plot_load_nemo.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/a3ff34e87f0049496d17c4d9c04fc225d256971392d39f1696df0f16cec00f36.png"
],
- "example_tests.test_orca_projection.TestOrcaProjection.test_orca_projection.0": [
+ "gallery_tests.test_plot_orca_projection.TestOrcaProjection.test_plot_orca_projection.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/fb11731a94cea4ee64b35e91d1d2304e9e5ac7397b20e1fe12852487e666ce46.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/bb11721a87cce5e4cce79e81d19b3b5e1e1cd3783168e07835853485e65e2e1e.png"
],
- "example_tests.test_orca_projection.TestOrcaProjection.test_orca_projection.1": [
+ "gallery_tests.test_plot_orca_projection.TestOrcaProjection.test_plot_orca_projection.1": [
"https://scitools.github.io/test-iris-imagehash/images/v4/e5a665a69a599659e5db1865c2653b869996cce63e99e19a1a912639e7181e65.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e58661969e799659c1f719a6c867359a1996c0773649c09c3e612679c07b3f66.png"
],
- "example_tests.test_orca_projection.TestOrcaProjection.test_orca_projection.2": [
+ "gallery_tests.test_plot_orca_projection.TestOrcaProjection.test_plot_orca_projection.2": [
"https://scitools.github.io/test-iris-imagehash/images/v4/f2c464ce9e399332e1b74ce1cc79338c6586e5b33b31b37a66c9664cc06e1a64.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/a58660ce9e739b31c93d1cc9c8df33863383e33b3f11c03f2664366cc8ee3cc1.png"
],
- "example_tests.test_orca_projection.TestOrcaProjection.test_orca_projection.3": [
+ "gallery_tests.test_plot_orca_projection.TestOrcaProjection.test_plot_orca_projection.3": [
"https://scitools.github.io/test-iris-imagehash/images/v4/fa817a83846ea46ce539c93391de32cc86cf87a33fa168721cdb3e896e374b04.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/be817a87845ea56cec79817a919e338436a5c1e73fa16c736c4a3e816a1e6b1c.png"
],
- "example_tests.test_polar_stereo.TestPolarStereo.test_polar_stereo.0": [
+ "gallery_tests.test_plot_polar_stereo.TestPolarStereo.test_plot_polar_stereo.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/e168317a92d36d89c5bb9e94c55e6f0c9a93c15a6ec584763b21716791de3a81.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/b9e16079971e9e93c8ce0f84c31e3b929f92c0ff3ca1c17e39e03961c07e3f80.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ba1e615ec7e097a9961f9cb190f838e091c2c1e73f07c11f6f386b3cc1783e11.png"
],
- "example_tests.test_polynomial_fit.TestPolynomialFit.test_polynomial_fit.0": [
+ "gallery_tests.test_plot_polynomial_fit.TestPolynomialFit.test_plot_polynomial_fit.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/abff4a9df26435886520c97f12414695c4b69d23934bc86adc969237d68ccc6f.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/aaff4a9df26435886520c97f12414695c4b69d23934bc86adc969a17d69ccc6f.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/aeffcb34d244348be5a2c96c3a4fc6d0c4b69f2d87294ccb9f1a125684cd7c11.png"
],
- "example_tests.test_projections_and_annotations.TestProjectionsAndAnnotations.test_projections_and_annotations.0": [
+ "gallery_tests.test_plot_projections_and_annotations.TestProjectionsAndAnnotations.test_plot_projections_and_annotations.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/fa854f19851a30e4cc76cd0bb179325ca7c665b0c938cb4b4e719e9cb727b5c0.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fac54f19851a30e4cc76cd0bb179325cb78665b0c938cb4b4e719e9c9727b5c0.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fa854e19851a30e4cc76cd0bb179325cb7c664b0c938cb4bce739e9c37a3b5c0.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fa854e19851a30e4cc76cd0bb179325cb78665b1c938c94bce739e9c3727b5c0.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fa854f19851a30e4cc76cd0bb0f932dca7c665b1c92ccb4b4ed19e9c3721b5c8.png"
],
- "example_tests.test_projections_and_annotations.TestProjectionsAndAnnotations.test_projections_and_annotations.1": [
+ "gallery_tests.test_plot_projections_and_annotations.TestProjectionsAndAnnotations.test_plot_projections_and_annotations.1": [
"https://scitools.github.io/test-iris-imagehash/images/v4/e385699d9c3896627243318fcdad5a7dc6dba492e9b69964936dc21974b18592.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e385699d9c3896727243318f8dad5a7dc65ba492b93699649b6dc25b64938592.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e385699d9c3896627243318fcdad5a7dc6dba492b93699649b6dc25964938592.png",
@@ -131,29 +131,29 @@
"https://scitools.github.io/test-iris-imagehash/images/v4/e3856b999c3896727243318f8dad5a75865ba492e9b69964db6cc65b74918592.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e3856d999c389662734731afcdad5a7384daa592b1b69b64d26dc29974b18590.png"
],
- "example_tests.test_rotated_pole_mapping.TestRotatedPoleMapping.test_rotated_pole_mapping.0": [
+ "gallery_tests.test_plot_rotated_pole_mapping.TestRotatedPoleMapping.test_plot_rotated_pole_mapping.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/fa15615e97a193adc15e1e81c4fa3eb49d30817e3e05c17e7ba59927817e1e01.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ee46607e97a19781c0df1f81d0bb3e241f20c16f3fc0c1fe39263d33d06f3e80.png"
],
- "example_tests.test_rotated_pole_mapping.TestRotatedPoleMapping.test_rotated_pole_mapping.1": [
+ "gallery_tests.test_plot_rotated_pole_mapping.TestRotatedPoleMapping.test_plot_rotated_pole_mapping.1": [
"https://scitools.github.io/test-iris-imagehash/images/v4/ba056717c3e099e9b90f8e81c4da589499b696763e45e56b3b893929c17b7e01.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ea57685f95a886a1c0de9da090be3e2697e1c0ff3f00c17e6b266c17c07f3f00.png"
],
- "example_tests.test_rotated_pole_mapping.TestRotatedPoleMapping.test_rotated_pole_mapping.2": [
+ "gallery_tests.test_plot_rotated_pole_mapping.TestRotatedPoleMapping.test_plot_rotated_pole_mapping.2": [
"https://scitools.github.io/test-iris-imagehash/images/v4/ba1e605ec7a191a1b85e9e81c4da58909996b37e3a65e16f7b817939e57a1e01.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ba1e605ec7a193a1b85e9e81c4da58909996b3763a65e16f7b816939ed7a1e01.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e85a697e97a18681c6da9f8190bf3e263624c1ef3b48c17a2b223c47c0ff3f81.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/ea57685f95a886a1c0de9da090be3e2497e1c0ef3f01c17e6b366c17c07b3f01.png"
],
- "example_tests.test_rotated_pole_mapping.TestRotatedPoleMapping.test_rotated_pole_mapping.3": [
+ "gallery_tests.test_plot_rotated_pole_mapping.TestRotatedPoleMapping.test_plot_rotated_pole_mapping.3": [
"https://scitools.github.io/test-iris-imagehash/images/v4/fa8172d0847ecd2bc913939c36846c714933799cc3cc8727e67639f939996a58.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/fa8172c6857ecd38cb3392ce36c564311931d85ec64e9787719a39993c316e66.png"
],
- "example_tests.test_wind_speed.TestWindSpeed.test_wind_speed.0": [
+ "gallery_tests.test_plot_wind_speed.TestWindSpeed.test_plot_wind_speed.0": [
"https://scitools.github.io/test-iris-imagehash/images/v4/bcf924fb9306930ce12ccf97c73236b28ecec4cd3e29847b18e639e6c14f1a09.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e9e960e996169306c1ee9e96c29e36739e13c07d3d61c07f39a139a1c07f3f01.png"
],
- "example_tests.test_wind_speed.TestWindSpeed.test_wind_speed.1": [
+ "gallery_tests.test_plot_wind_speed.TestWindSpeed.test_plot_wind_speed.1": [
"https://scitools.github.io/test-iris-imagehash/images/v4/bcf924fb9306930ce12ccf97c73236b28ecec4cc3e29847b38e639e6c14f1a09.png",
"https://scitools.github.io/test-iris-imagehash/images/v4/e9e960e996169306c1ee9e86c29e36739e13c07d3d61c07f39a139a1c17f3f01.png"
],
diff --git a/lib/iris/tests/runner/_runner.py b/lib/iris/tests/runner/_runner.py
index 8175e7b19f..71b6e5fcc6 100644
--- a/lib/iris/tests/runner/_runner.py
+++ b/lib/iris/tests/runner/_runner.py
@@ -21,7 +21,7 @@ class TestRunner:
description = (
"Run tests under nose and multiprocessor for performance. "
- "Default behaviour is to run all non-example tests. "
+ "Default behaviour is to run all non-gallery tests. "
"Specifying one or more test flags will run *only* those "
"tests."
)
@@ -34,7 +34,7 @@ class TestRunner:
),
("stop", "x", "Stop running tests after the first error or failure."),
("system-tests", "s", "Run the limited subset of system tests."),
- ("example-tests", "e", "Run the example code tests."),
+ ("gallery-tests", "e", "Run the gallery code tests."),
("default-tests", "d", "Run the default tests."),
(
"coding-tests",
@@ -53,7 +53,7 @@ class TestRunner:
"no-data",
"system-tests",
"stop",
- "example-tests",
+ "gallery-tests",
"default-tests",
"coding-tests",
"create-missing",
@@ -63,7 +63,7 @@ def initialize_options(self):
self.no_data = False
self.stop = False
self.system_tests = False
- self.example_tests = False
+ self.gallery_tests = False
self.default_tests = False
self.coding_tests = False
self.num_processors = None
@@ -87,8 +87,8 @@ def finalize_options(self):
tests.append("default")
if self.coding_tests:
tests.append("coding")
- if self.example_tests:
- tests.append("example")
+ if self.gallery_tests:
+ tests.append("gallery")
if not tests:
tests.append("default")
print("Running test suite(s): {}".format(", ".join(tests)))
@@ -114,19 +114,19 @@ def run(self):
tests.append("iris.tests")
if self.coding_tests:
tests.append("iris.tests.test_coding_standards")
- if self.example_tests:
+ if self.gallery_tests:
import iris.config
default_doc_path = os.path.join(sys.path[0], "docs", "iris")
doc_path = iris.config.get_option(
"Resources", "doc_dir", default=default_doc_path
)
- example_path = os.path.join(doc_path, "example_tests")
- if os.path.exists(example_path):
- tests.append(example_path)
+ gallery_path = os.path.join(doc_path, "gallery_tests")
+ if os.path.exists(gallery_path):
+ tests.append(gallery_path)
else:
print(
- "WARNING: Example path %s does not exist." % (example_path)
+ "WARNING: Gallery path %s does not exist." % (gallery_path)
)
if not tests:
tests.append("iris.tests")
diff --git a/lib/iris/tests/test_coding_standards.py b/lib/iris/tests/test_coding_standards.py
index cfb54203b3..00ce7b7d44 100644
--- a/lib/iris/tests/test_coding_standards.py
+++ b/lib/iris/tests/test_coding_standards.py
@@ -104,13 +104,12 @@ def test_license_headers(self):
"setup.py",
"build/*",
"dist/*",
- "docs/iris/example_code/*/*.py",
+ "docs/iris/gallery_code/*/*.py",
"docs/iris/src/developers_guide/documenting/*.py",
- "docs/iris/src/sphinxext/gen_gallery.py",
"docs/iris/src/userguide/plotting_examples/*.py",
"docs/iris/src/userguide/regridding_plots/*.py",
"docs/iris/src/developers_guide/gitwash_dumper.py",
- "docs/iris/build/*",
+ "docs/iris/src/_build/*",
"lib/iris/analysis/_scipy_interpolate.py",
"lib/iris/fileformats/_pyke_rules/*",
)
diff --git a/requirements/docs.txt b/requirements/docs.txt
index 6966869c70..2d2c03f688 100644
--- a/requirements/docs.txt
+++ b/requirements/docs.txt
@@ -1 +1,4 @@
sphinx
+sphinx_rtd_theme
+sphinx-copybutton
+sphinx-gallery
diff --git a/setup.py b/setup.py
index e5dd0e7bb9..b078e3de1f 100644
--- a/setup.py
+++ b/setup.py
@@ -181,7 +181,6 @@ def build_std_names(cmd, directory):
xml_path = os.path.join("etc", "cf-standard-name-table.xml")
module_path = os.path.join(directory, "iris", "std_names.py")
args = (sys.executable, script_path, xml_path, module_path)
-
cmd.spawn(args)
diff --git a/tools/generate_std_names.py b/tools/generate_std_names.py
index 3aad3bb09c..95dcce8171 100644
--- a/tools/generate_std_names.py
+++ b/tools/generate_std_names.py
@@ -35,14 +35,17 @@
This file is automatically generated. Do not edit this file by hand.
-The file will be generated during a standard build/installation:
+The file will be generated during a standard build/installation::
+
python setup.py build
python setup.py install
-Also, the file can be re-generated in the source distribution via:
+Also, the file can be re-generated in the source distribution via::
+
python setup.py std_names
-Or for more control (e.g. to use an alternative XML file) via:
+Or for more control (e.g. to use an alternative XML file) via::
+
python tools/generate_std_names.py XML_FILE MODULE_FILE
"""
-
-
-
-