From f4a8f5a6717a3c9940f4c2806eb661f83f917f95 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Thu, 12 Sep 2019 11:58:33 +0100 Subject: [PATCH 1/9] test version of travis --- .travis.yml | 22 ++++++++-------------- docs/iris/src/_templates/index.html | 2 +- docs/iris/src/_templates/layout.html | 2 +- docs/iris/src/whatsnew/index.rst | 1 + 4 files changed, 11 insertions(+), 16 deletions(-) diff --git a/.travis.yml b/.travis.yml index 22dae9e12f..bfa89b12d3 100644 --- a/.travis.yml +++ b/.travis.yml @@ -13,18 +13,6 @@ env: # The decryption key for the encrypted .github/deploy_key.scitools-docs.enc. - secure: "N9/qBUT5CqfC7KQBDy5mIWZcGNuUJk3e/qmKJpotWYV+zwOI4GghJsRce6nFnlRiwl65l5oBEcvf3+sBvUfbZqh7U0MdHpw2tHhr2FSCmMB3bkvARZblh9M37f4da9G9VmRkqnyBM5G5TImXtoq4dusvNWKvLW0qETciaipq7ws=" matrix: - - PYTHON_VERSION=2.7 TEST_TARGET=default TEST_MINIMAL=true - - PYTHON_VERSION=2.7 TEST_TARGET=default - - PYTHON_VERSION=2.7 TEST_TARGET=example - - - PYTHON_VERSION=3.6 TEST_TARGET=default TEST_MINIMAL=true - - PYTHON_VERSION=3.6 TEST_TARGET=default - - PYTHON_VERSION=3.6 TEST_TARGET=example - - PYTHON_VERSION=3.6 TEST_TARGET=doctest - - - 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 git: @@ -137,6 +125,12 @@ script: - > if [[ ${TEST_TARGET} == 'doctest' ]]; then + cd ${INSTALL_DIR}/docs/iris/src/whatsnew; + WHATSNEW=$(ls -d contributions_* 2>/dev/null); + if [[ "$WHATSNEW" != "" ]]; then + VERSION=$(echo $WHATSNEW | grep -o "[[:digit:].]*"); + python aggregate_directory.py $VERSION; + fi; MPL_RC_DIR="${HOME}/.config/matplotlib"; mkdir -p ${MPL_RC_DIR}; echo 'backend : agg' > ${MPL_RC_DIR}/matplotlibrc; @@ -148,8 +142,8 @@ 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, and we are running in python 3, push some docs. + - if [[ ${TEST_TARGET} == 'doctest' && ${TRAVIS_EVENT_TYPE} == 'push' && ${PYTHON_VERSION} == 3.7 && ${ORG} == "SciTools" ]]; then cd ${INSTALL_DIR}; pip install doctr; doctr deploy --deploy-repo SciTools-docs/iris --built-docs docs/iris/build/html diff --git a/docs/iris/src/_templates/index.html b/docs/iris/src/_templates/index.html index 31acded447..e9f9b16111 100644 --- a/docs/iris/src/_templates/index.html +++ b/docs/iris/src/_templates/index.html @@ -134,7 +134,7 @@ extra information on specific technical issues

  • -

    What's new in Iris 2.2?
    +

    What's new in Iris 2.3?
    recent changes in Iris's capabilities

    • diff --git a/docs/iris/src/_templates/layout.html b/docs/iris/src/_templates/layout.html index 8ecc35bade..22b91223d2 100644 --- a/docs/iris/src/_templates/layout.html +++ b/docs/iris/src/_templates/layout.html @@ -37,7 +37,7 @@

    - Iris v2.2 + Iris v2.3

    A powerful, format-agnostic, community-driven Python library for analysing and diff --git a/docs/iris/src/whatsnew/index.rst b/docs/iris/src/whatsnew/index.rst index c3a34303f0..a4a472de53 100644 --- a/docs/iris/src/whatsnew/index.rst +++ b/docs/iris/src/whatsnew/index.rst @@ -9,6 +9,7 @@ Iris versions. .. toctree:: :maxdepth: 2 + 2.3.rst 2.2.rst 2.1.rst 2.0.rst From 235c3d4b16b2ef34c1dd8a176c3ab8947962400e Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Thu, 12 Sep 2019 16:34:21 +0100 Subject: [PATCH 2/9] Fix docs pushing and add a whatsnew build. --- .travis.yml | 41 +++++++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/.travis.yml b/.travis.yml index bfa89b12d3..dc383f0cbe 100644 --- a/.travis.yml +++ b/.travis.yml @@ -13,7 +13,19 @@ env: # The decryption key for the encrypted .github/deploy_key.scitools-docs.enc. - secure: "N9/qBUT5CqfC7KQBDy5mIWZcGNuUJk3e/qmKJpotWYV+zwOI4GghJsRce6nFnlRiwl65l5oBEcvf3+sBvUfbZqh7U0MdHpw2tHhr2FSCmMB3bkvARZblh9M37f4da9G9VmRkqnyBM5G5TImXtoq4dusvNWKvLW0qETciaipq7ws=" matrix: - - PYTHON_VERSION=3.7 TEST_TARGET=doctest + - PYTHON_VERSION=2.7 TEST_TARGET=default TEST_MINIMAL=true + - PYTHON_VERSION=2.7 TEST_TARGET=default + - PYTHON_VERSION=2.7 TEST_TARGET=example + + - PYTHON_VERSION=3.6 TEST_TARGET=default TEST_MINIMAL=true + - PYTHON_VERSION=3.6 TEST_TARGET=default + - PYTHON_VERSION=3.6 TEST_TARGET=example + - PYTHON_VERSION=3.6 TEST_TARGET=doctest + + - 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 PUSH_BUILT_DOCS=true git: # We need a deep clone so that we can compute the age of the files using their git history. @@ -123,14 +135,27 @@ 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 with 'aggregate_directory.py', before the build. - > - if [[ ${TEST_TARGET} == 'doctest' ]]; then + if [[ ${PUSH_BUILT_DOCS} == 'true' ]] then cd ${INSTALL_DIR}/docs/iris/src/whatsnew; WHATSNEW=$(ls -d contributions_* 2>/dev/null); if [[ "$WHATSNEW" != "" ]]; then VERSION=$(echo $WHATSNEW | grep -o "[[:digit:].]*"); python aggregate_directory.py $VERSION; fi; + fi + + # Build the docs. + - > + if [[ ${TEST_TARGET} == 'doctest' ]]; then MPL_RC_DIR="${HOME}/.config/matplotlib"; mkdir -p ${MPL_RC_DIR}; echo 'backend : agg' > ${MPL_RC_DIR}/matplotlibrc; @@ -142,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' && ${PYTHON_VERSION} == 3.7 && ${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/<>/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 @@ -152,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 From d624954561fed9f1dceb802d033e3b9e11e29cb2 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Thu, 12 Sep 2019 16:34:53 +0100 Subject: [PATCH 3/9] Crude attempt to make automatic whatsnew aggregation more readable. --- docs/iris/src/whatsnew/aggregate_directory.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/iris/src/whatsnew/aggregate_directory.py b/docs/iris/src/whatsnew/aggregate_directory.py index 88290907ef..b8258a1b08 100644 --- a/docs/iris/src/whatsnew/aggregate_directory.py +++ b/docs/iris/src/whatsnew/aggregate_directory.py @@ -242,6 +242,7 @@ 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 From 7c401a893c1ad594367a7e5e97ba5d7342a28d99 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Thu, 12 Sep 2019 16:43:51 +0100 Subject: [PATCH 4/9] Licence header fix. --- docs/iris/src/whatsnew/aggregate_directory.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/iris/src/whatsnew/aggregate_directory.py b/docs/iris/src/whatsnew/aggregate_directory.py index b8258a1b08..adae9fe5b4 100644 --- a/docs/iris/src/whatsnew/aggregate_directory.py +++ b/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. # From 7ad2d744fbe20f6411bd4e385a3cedc91d8ee41b Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Thu, 12 Sep 2019 16:53:30 +0100 Subject: [PATCH 5/9] Script syntax fix. --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index dc383f0cbe..ea7810cd0a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -144,7 +144,7 @@ script: # When pushing built docs, attempt to make a preliminary whatsnew with 'aggregate_directory.py', before the build. - > - if [[ ${PUSH_BUILT_DOCS} == 'true' ]] then + if [[ ${PUSH_BUILT_DOCS} == 'true' ]]; then cd ${INSTALL_DIR}/docs/iris/src/whatsnew; WHATSNEW=$(ls -d contributions_* 2>/dev/null); if [[ "$WHATSNEW" != "" ]]; then From 7419f8839510d8b784bcca9567fe5ac9a9aaa68a Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Thu, 12 Sep 2019 18:22:08 +0100 Subject: [PATCH 6/9] Reference the latest-docs build in the README. --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index f1f98f6233..c2be37d54f 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,11 @@ use of standard NumPy/dask arrays as its underlying data storage. The documentation for Iris is available at , including a user guide, example code, and gallery. +## Work in progress + +A documentation build for the latest development code is visible at +. + # Installation The easiest way to install Iris is with [conda](https://conda.io/miniconda.html): From 16b963028da2db0edb83605e86c63cdf87abff02 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 16 Sep 2019 12:10:51 +0100 Subject: [PATCH 7/9] Review changes; treat interim release as a special case. --- .travis.yml | 3 +- README.md | 3 ++ docs/iris/src/_templates/index.html | 2 +- docs/iris/src/whatsnew/aggregate_directory.py | 36 +++++++++++++------ docs/iris/src/whatsnew/index.rst | 1 + 5 files changed, 32 insertions(+), 13 deletions(-) diff --git a/.travis.yml b/.travis.yml index ea7810cd0a..36fbc9dc31 100644 --- a/.travis.yml +++ b/.travis.yml @@ -142,7 +142,8 @@ script: python aggregate_directory.py --checkonly; fi - # When pushing built docs, attempt to make a preliminary whatsnew with 'aggregate_directory.py', before the build. + # 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; diff --git a/README.md b/README.md index c2be37d54f..7d97b9b599 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,9 @@ Travis-CI + +Master docs build zenodo diff --git a/docs/iris/src/_templates/index.html b/docs/iris/src/_templates/index.html index e9f9b16111..068a6fc09b 100644 --- a/docs/iris/src/_templates/index.html +++ b/docs/iris/src/_templates/index.html @@ -134,7 +134,7 @@ extra information on specific technical issues

  • -

    What's new in Iris 2.3?
    +

    What's new in Iris 2.3?
    recent changes in Iris's capabilities

    • diff --git a/docs/iris/src/whatsnew/aggregate_directory.py b/docs/iris/src/whatsnew/aggregate_directory.py index adae9fe5b4..fca098f4d4 100644 --- a/docs/iris/src/whatsnew/aggregate_directory.py +++ b/docs/iris/src/whatsnew/aggregate_directory.py @@ -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 = '' + 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 = '' 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 = [] @@ -247,7 +252,7 @@ def compile_directory(directory, release): 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. @@ -264,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 ! @@ -279,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: @@ -296,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 '', " + "and its date as ''.")) 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) diff --git a/docs/iris/src/whatsnew/index.rst b/docs/iris/src/whatsnew/index.rst index a4a472de53..4341738d25 100644 --- a/docs/iris/src/whatsnew/index.rst +++ b/docs/iris/src/whatsnew/index.rst @@ -9,6 +9,7 @@ Iris versions. .. toctree:: :maxdepth: 2 + latest.rst 2.3.rst 2.2.rst 2.1.rst From 04d84401bcf6b7facdedacc5d95c481de6317495 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 16 Sep 2019 13:03:00 +0100 Subject: [PATCH 8/9] Update Travis to use 'interim' whatsnew aggregation. --- .travis.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.travis.yml b/.travis.yml index 36fbc9dc31..06e450f95b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -149,8 +149,7 @@ script: cd ${INSTALL_DIR}/docs/iris/src/whatsnew; WHATSNEW=$(ls -d contributions_* 2>/dev/null); if [[ "$WHATSNEW" != "" ]]; then - VERSION=$(echo $WHATSNEW | grep -o "[[:digit:].]*"); - python aggregate_directory.py $VERSION; + python aggregate_directory.py --unreleased; fi; fi From e238f11b95990e85e1740ba021dc28a76bb3b255 Mon Sep 17 00:00:00 2001 From: Patrick Peglar Date: Mon, 16 Sep 2019 14:55:54 +0100 Subject: [PATCH 9/9] Remove extra section in readme page. --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 7d97b9b599..4b42ff98b1 100644 --- a/README.md +++ b/README.md @@ -88,8 +88,6 @@ use of standard NumPy/dask arrays as its underlying data storage. The documentation for Iris is available at , including a user guide, example code, and gallery. -## Work in progress - A documentation build for the latest development code is visible at .