Auto branch docs

.travis.yml

@@ -25,7 +25,7 @@ env:
     - PYTHON_VERSION=3.7 TEST_TARGET=default TEST_MINIMAL=true
     - PYTHON_VERSION=3.7 TEST_TARGET=default
     - PYTHON_VERSION=3.7 TEST_TARGET=example
-    - PYTHON_VERSION=3.7 TEST_TARGET=doctest
+    - PYTHON_VERSION=3.7 TEST_TARGET=doctest PUSH_BUILT_DOCS=true
 
 git:
   # We need a deep clone so that we can compute the age of the files using their git history.
@@ -135,6 +135,25 @@ script:
       python -m iris.tests.runner --example-tests --print-failed-images;
     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 [[ "$WHATSNEW" != "" ]]; then
+        python aggregate_directory.py --unreleased;
+      fi;
+    fi
+
+  # Build the docs.
   - >
     if [[ ${TEST_TARGET} == 'doctest' ]]; then
       MPL_RC_DIR="${HOME}/.config/matplotlib";
@@ -148,8 +167,10 @@ script:
   # Split the organisation out of the slug. See https://stackoverflow.com/a/5257398/741316 for description.
   - ORG=(${TRAVIS_REPO_SLUG//\// })
 
-  # When we merge a change, and we are running in python 3, push some docs. 
-  - if [[ ${TEST_TARGET} == 'doctest' && ${TRAVIS_EVENT_TYPE} == 'push' && ${TRAVIS_PYTHON_VERSION} == 3* && ${ORG} == "SciTools" ]]; then
+  # When we merge a change to SciTools/iris, we can push docs to github pages.
+  # At present, only the Python 3.7 "doctest" job does this.
+  # Results appear at https://scitools-docs.github.io/iris/<<branchname>>/index.html
+  - if [[ ${ORG} == "SciTools" && ${TRAVIS_EVENT_TYPE} == 'push' && ${PUSH_BUILT_DOCS} == 'true' ]]; then
       cd ${INSTALL_DIR};
       pip install doctr;
       doctr deploy --deploy-repo SciTools-docs/iris --built-docs docs/iris/build/html
@@ -158,9 +179,3 @@ script:
         ${TRAVIS_BRANCH:-${TRAVIS_TAG}};
     fi
 
-  # An extra 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

README.md

@@ -26,6 +26,9 @@
 <a href="https://travis-ci.org/SciTools/iris/branches">
 <img src="https://api.travis-ci.org/repositories/SciTools/iris.svg?branch=master"
      alt="Travis-CI" /></a>
+<a href="https://scitools-docs.github.io/iris/master/index.html">
+<img src="https://img.shields.io/badge/docs-master-blue.svg"
+     alt="Master docs build" /></a>
 <a href="https://zenodo.org/badge/latestdoi/5312648">
 <img src="https://zenodo.org/badge/5312648.svg"
      alt="zenodo" /></a>
@@ -85,6 +88,9 @@ use of standard NumPy/dask arrays as its underlying data storage.
 The documentation for Iris is available at <https://scitools.org.uk/iris/docs/latest>,
 including a user guide, example code, and gallery.
 
+A documentation build for the latest development code is visible at
+<https://scitools-docs.github.io/iris/master/index.html>.
+
 # Installation
 
 The easiest way to install Iris is with [conda](https://conda.io/miniconda.html):

docs/iris/src/_templates/index.html

@@ -134,7 +134,7 @@
         <span class="linkdescr">extra information on specific technical issues</span></p>
     </li>
     <li>
-        <p class="biglink"><a class="biglink" href="whatsnew/2.2.html">What's new in Iris 2.2?</a><br/>
+        <p class="biglink"><a class="biglink" href="whatsnew/latest.html">What's new in Iris 2.3?</a><br/>
         <span class="linkdescr">recent changes in Iris's capabilities</span></p>
     </li>
 	</ul>

docs/iris/src/_templates/layout.html

@@ -37,7 +37,7 @@
     </a>
     <div class="strapline">
       <h1>
-          Iris <span class="version">v2.2</span>
+          Iris <span class="version">v2.3</span>
       </h1>
       <p>
          A powerful, format-agnostic, community-driven Python library for analysing and

docs/iris/src/whatsnew/aggregate_directory.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2015 - 2016, Met Office
+# (C) British Crown Copyright 2015 - 2019, Met Office
 #
 # This file is part of Iris.
 #
@@ -166,13 +166,16 @@ def find_release_directory(root_directory, release=None,
     return result
 
 
-def generate_header(release):
+def generate_header(release, unreleased=False):
     '''Return a list of text lines that make up a header for the document.'''
+    if unreleased:
+        isodatestamp = '<unreleased>'
+    else:
+        isodatestamp = datetime.date.today().strftime('%Y-%m-%d')
     header_text = []
     title_template = 'What\'s New in {} {!s}\n'
     title_line = title_template.format(SOFTWARE_NAME, release)
     title_underline = ('*' * (len(title_line) - 1)) + '\n'
-    isodatestamp = datetime.date.today().strftime('%Y-%m-%d')
     header_text.append(title_line)
     header_text.append(title_underline)
     header_text.append('\n')
@@ -215,11 +218,13 @@ def read_directory(directory_path):
     return compilable_files
 
 
-def compile_directory(directory, release):
+def compile_directory(directory, release, unreleased=False):
     '''Read in source files in date order and compile the text into a list.'''
+    if unreleased:
+        release = '<interim>'
     source_text = read_directory(directory)
     compiled_text = []
-    header_text = generate_header(release)
+    header_text = generate_header(release, unreleased)
     compiled_text.extend(header_text)
     for count, category in enumerate(VALID_CATEGORIES):
         category_text = []
@@ -242,11 +247,12 @@ def compile_directory(directory, release):
                 if not text[-1].endswith('\n'):
                     text[-1] += '\n'
                 category_text.extend(text)
+            category_text.append('\n----\n\n')
         compiled_text.extend(category_text)
     return compiled_text
 
 
-def check_all_contributions_valid(release=None, quiet=False):
+def check_all_contributions_valid(release=None, quiet=False, unreleased=False):
     """"Scan the contributions directory for badly-named files."""
     root_directory = _self_root_directory()
     # Check there are *some* contributions directory(s), else silently pass.
@@ -263,12 +269,12 @@ def check_all_contributions_valid(release=None, quiet=False):
         # Run the directory scan, but convert any warning into an error.
         with warnings.catch_warnings():
             warnings.simplefilter('error')
-            compile_directory(release_directory, release)
+            compile_directory(release_directory, release, unreleased)
     if not quiet:
         print('done.')
 
 
-def run_compilation(release=None, quiet=False):
+def run_compilation(release=None, quiet=False, unreleased=False):
     '''Write a draft release.rst file given a specified uncompiled release.'''
     if release is None:
         # This must exist !
@@ -278,8 +284,11 @@ def run_compilation(release=None, quiet=False):
         print(msg.format(release))
     root_directory = _self_root_directory()
     release_directory = find_release_directory(root_directory, release)
-    compiled_text = compile_directory(release_directory, release)
-    compiled_filename = str(release) + EXTENSION
+    compiled_text = compile_directory(release_directory, release, unreleased)
+    if unreleased:
+        compiled_filename = 'latest' + EXTENSION
+    else:
+        compiled_filename = str(release) + EXTENSION
     compiled_filepath = os.path.join(root_directory, compiled_filename)
     with open(compiled_filepath, 'w') as output_object:
         for string_line in compiled_text:
@@ -295,13 +304,19 @@ def run_compilation(release=None, quiet=False):
     PARSER.add_argument(
         '-c', '--checkonly', action='store_true',
         help="Check contribution file names, do not build.")
+    PARSER.add_argument(
+        '-u', '--unreleased', action='store_true',
+        help=("Label the release version as '<interim>', "
+              "and its date as '<unreleased>'."))
     PARSER.add_argument(
         '-q', '--quiet', action='store_true',
         help="Do not print progress messages.")
     ARGUMENTS = PARSER.parse_args()
     release = ARGUMENTS.release
+    unreleased = ARGUMENTS.unreleased
     quiet = ARGUMENTS.quiet
     if ARGUMENTS.checkonly:
-        check_all_contributions_valid(release, quiet=quiet)
+        check_all_contributions_valid(release, quiet=quiet,
+                                      unreleased=unreleased)
     else:
-        run_compilation(release, quiet=quiet)
+        run_compilation(release, quiet=quiet, unreleased=unreleased)

docs/iris/src/whatsnew/index.rst

@@ -9,6 +9,8 @@ Iris versions.
 .. toctree::
    :maxdepth: 2
 
+   latest.rst
+   2.3.rst
    2.2.rst
    2.1.rst
    2.0.rst