diff --git a/.travis.yml b/.travis.yml index 22dae9e12f..06e450f95b 100644 --- a/.travis.yml +++ b/.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/<>/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 diff --git a/README.md b/README.md index f1f98f6233..4b42ff98b1 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,9 @@ Travis-CI + +Master docs build zenodo @@ -85,6 +88,9 @@ 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. +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): diff --git a/docs/iris/src/_templates/index.html b/docs/iris/src/_templates/index.html index 31acded447..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.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/aggregate_directory.py b/docs/iris/src/whatsnew/aggregate_directory.py index 88290907ef..fca098f4d4 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. # @@ -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 = [] @@ -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 '', " + "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 c3a34303f0..4341738d25 100644 --- a/docs/iris/src/whatsnew/index.rst +++ b/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