whatsnew overhaul (SciTools#3769)

* whatsnew overhaul * corrected link * various corrections * typo fix * Update docs/iris/src/developers_guide/documenting/whats_new_contributions.rst Co-authored-by: Patrick Peglar <[email protected]> * Âwording improvements Co-authored-by: Patrick Peglar <[email protected]>
owena11 · Aug 19, 2020 · cb8aa95 · cb8aa95
1 parent 660fd34
commit cb8aa95
Show file tree

Hide file tree

Showing 53 changed files with 1,920 additions and 1,360 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -122,25 +122,6 @@ script:
       python -m iris.tests.runner --gallery-tests;
     fi
 
-  # A call to check "whatsnew" contributions are valid, because the Iris test
-  # for it needs a *developer* install to be able to find the docs.
-  - >
-    if [[ "${TEST_TARGET}" == 'doctest' ]]; then
-      cd ${INSTALL_DIR}/docs/iris/src/whatsnew;
-      python aggregate_directory.py --checkonly;
-    fi
-
-  # When pushing built docs, attempt to make a preliminary whatsnew by calling
-  # 'aggregate_directory.py', before the build.
-  - >
-    if [[ "${PUSH_BUILT_DOCS}" == 'true' ]]; then
-      cd ${INSTALL_DIR}/docs/iris/src/whatsnew;
-      WHATSNEW=$(ls -d contributions_* 2>/dev/null);
-      if [[ -n "${WHATSNEW}" ]]; then
-        python aggregate_directory.py --unreleased;
-      fi;
-    fi
-
   # Build the docs.
   - >
     if [[ "${TEST_TARGET}" == 'doctest' ]]; then

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

diff --git a/docs/iris/src/conf.py b/docs/iris/src/conf.py
@@ -36,6 +36,13 @@ def autolog(message):
 if on_rtd:
     autolog("Build running on READTHEDOCS server")
 
+    # list all the READTHEDOCS environment variables that may be of use
+    # at some point
+    autolog("Listing all environment variables on the READTHEDOCS server...")
+
+    for item, value in os.environ.items():
+        autolog("[READTHEDOCS] {} = {}".format(item, value))
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,

diff --git a/docs/iris/src/developers_guide/contributing_documentation.rst b/docs/iris/src/developers_guide/contributing_documentation.rst
@@ -25,6 +25,8 @@ The documentation uses specific packages that need to be present.  Please see
 :ref:`installing_iris` for instructions.
 
 
+.. _contributing.documentation.building:
+
 Building
 --------
 

diff --git a/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst b/docs/iris/src/developers_guide/documenting/whats_new_contributions.rst
@@ -4,18 +4,14 @@
 Contributing a "What's New" entry
 =================================
 
-Iris has an aggregator for building a draft what's new document for each
-release. The draft what's new document is built from contributions by code authors.
-This means contributions to the what's new document are written by the
-developer most familiar with the change made.
+Iris uses a file named ``latest.rst`` to keep a draft of upcoming changes
+that will form the next release.  Contributions to the :ref:`iris_whatsnew`
+document are written by the developer most familiar with the change made.
+The contribution should be included as part of the Iris Pull Request that
+introduces the change.
 
-A contribution provides an entry in the what's new document, which describes a
-change that improved Iris in some way. This change may be a new feature in Iris
-or the fix for a bug introduced in a previous release. The contribution should
-be included as part of the Iris Pull Request that introduces the change.
-
-When a new release is prepared, the what's new contributions are combined into
-a draft what's new document for the release.
+The ``latest.rst`` and the past release notes are kept in 
+``docs/iris/src/whatsnew/``.
 
 
 Writing a contribution
@@ -26,98 +22,54 @@ which improved Iris in some way. As such, a single Iris Pull Request may
 contain multiple changes that are worth highlighting as contributions to the
 what's new document.
 
-Each contribution will ideally be written as a single concise bullet point.
-The content of the bullet point should highlight the change that has been made
-to Iris, targeting an Iris user as the audience.
-
-A contribution is a feature summary by the code author, which avoids the
-release developer having to personally review the change in detail :
-It is not in itself the final documentation content,
-so it does not have to be perfect or complete in every respect.
-
-
-Adding contribution files
-=========================
+Each contribution will ideally be written as a single concise bullet point
+in a reStructuredText format with a trailing blank line.  For example::
 
-Each release must have a directory called ``contributions_<release number>``,
-which should be created following the release of the current version of Iris. Each
-release directory must be placed in ``docs/iris/src/whatsnew/``.
-Contributions to the what's new must be written in markdown and placed into this
-directory in text files. The filename for each item should be structured as follows:
+  * Fixed :issue:`9999`.  Lorem ipsum dolor sit amet, consectetur adipiscing 
+    elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
+    <blank line>
 
-``<category>_<date>_<summary>.txt``
-
-Category
---------
-The category must be one of the following:
-
-*newfeature*
-  Features that are new or changed to add functionality.
-*bugfix*
-  A bugfix.
-*incompatiblechange*
-  A change that causes an incompatibility with prior versions of Iris.
-*deprecate*
-  Deprecations of functionality.
-*docchange*
-  Changes to documentation.
+Note that this example also cites the related issue, optionally you may also
+include the pull request using the notation ``:pull:`9999```.  Where possible
+do not exceed **column 80** and ensure that any subsequent lines
+of the same bullet point is aligned with the first.  
 
-Date
-----
-
-The date must be a hyphen-separated date in the format of:
-
- * a four digit year,
- * a three character month name, and
- * a two digit day.
-
-For example:
-
- * 2012-Jan-30
- * 2014-May-03
- * 2015-Feb-19
-
-Summary
--------
+The content of the bullet point should highlight the change that has been made
+to Iris, targeting an Iris user as the audience.
 
-The summary can be any remaining filename characters, and simply provides a
-short identifying description of the change.
+For inspiration that may include adding links to code please examine past
+what's :ref:`iris_whatsnew` entries.  
 
-For example:
+.. 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
+          creating a pull request, however you can also manually 
+          :ref:`build <contributing.documentation.building>` the documentation.
 
- * whats-new-aggregator
- * using_mo_pack
- * correction-to-bilinear-regrid
- * GRIB2_pdt11
+.. _travis-ci: https://travis-ci.org/github/SciTools/iris
 
 
-Complete examples
------------------
+Contribution categories
+=======================
 
-Some sample what's new contribution filenames:
+The structure of the what's new release note should be easy to read by
+users.  To achieve this several categories may be used.
 
- * bugfix_2015-Aug-18_partial_pp_constraints.txt
- * deprecate_2015-Nov-01_unit-module.txt
- * incompatiblechange_2015-Oct-12_GRIB_optional_Python3_unavailable.txt
- * newfeature_2015-Jul-03_pearsonr_rewrite.txt
+*Features*
+  Features that are new or changed to add functionality.
 
-.. note::
-    A test in the standard test suite ensures that all the contents of the
-    latest contributions directory conform to this naming scheme.
+*Bug Fixes*
+  A bug fix.
 
+*Incompatible Changes*
+  A change that causes an incompatibility with prior versions of Iris.
 
-Compiling a draft
-=================
+*Internal*
+  Changes to any internal or development related topics, such as testing,
+  environment dependencies etc
 
-Compiling a draft from the supplied contributions should be done when preparing
-a release. Running ``docs/iris/src/whatsnew/aggregate_directory.py`` with the
-release number as the argument will create a draft what's new with the name
-``<release>.rst`` file for the specified release, by aggregating the individual
-contributions from the relevant folder.
-Omitting the release number will build the latest version for which a
-contributions folder is present.
-This command fails if a file with the relevant name already exists.
+*Deprecations*
+  Deprecations of functionality.
 
-The resulting draft document is only a starting point, which the release
-developer will then edit to produce the final 'What's new in Iris x.x'
-documentation.
+*Documentation*
+  Changes to documentation.
-Original file line number
+Diff line change
@@ Expand Up @@
     :ref:`installing_iris` for instructions.
+    .. _contributing.documentation.building:
     Building
     --------
@@ Expand Down @@