diff --git a/docs/src/_static/theme_override.css b/docs/src/_static/theme_override.css index 5edc286630..c56b720f69 100644 --- a/docs/src/_static/theme_override.css +++ b/docs/src/_static/theme_override.css @@ -26,3 +26,17 @@ table.docutils td { word-wrap: break-word; } +/* Used for very strong warning */ +#slim-red-box-message { + background: #ff0000; + box-sizing: border-box; + color: #ffffff; + font-weight: normal; + padding: 0.5em; +} + +#slim-red-box-message a { + color: #ffffff; + font-weight: normal; + text-decoration:underline; +} diff --git a/docs/src/_templates/layout.html b/docs/src/_templates/layout.html index 9b4983697e..96a2e0913e 100644 --- a/docs/src/_templates/layout.html +++ b/docs/src/_templates/layout.html @@ -1,5 +1,27 @@ {% extends "!layout.html" %} +{# This uses blocks. See: + https://www.sphinx-doc.org/en/master/templating.html +#} + +/*---------------------------------------------------------------------------*/ + +{%- block document %} + {% if READTHEDOCS and rtd_version == 'latest' %} +
+ You are viewing the latest unreleased documentation + v{{ version }}. You may prefer a + stable + version. +
+

+ {%- endif %} + + {{ super() }} +{%- endblock %} + +/*-----------------------------------------------------z----------------------*/ + {% block menu %} {{ super() }} diff --git a/docs/src/common_links.inc b/docs/src/common_links.inc index 3c465b67dc..23a933367e 100644 --- a/docs/src/common_links.inc +++ b/docs/src/common_links.inc @@ -24,6 +24,7 @@ .. _New Issue: https://github.com/scitools/iris/issues/new/choose .. _pull request: https://github.com/SciTools/iris/pulls .. _pull requests: https://github.com/SciTools/iris/pulls +.. _Read the Docs: https://scitools-iris.readthedocs.io/en/latest/ .. _readthedocs.yml: https://github.com/SciTools/iris/blob/master/requirements/ci/readthedocs.yml .. _SciTools: https://github.com/SciTools .. _sphinx: https://www.sphinx-doc.org/en/master/ diff --git a/docs/src/conf.py b/docs/src/conf.py index 9bab5850b8..ab05312fca 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -43,6 +43,9 @@ def autolog(message): for item, value in os.environ.items(): autolog("[READTHEDOCS] {} = {}".format(item, value)) +# This is the rtd reference to the version, such as: latest, stable, v3.0.1 etc +# For local testing purposes this could be explicitly set latest or stable. +rtd_version = os.environ.get("READTHEDOCS_VERSION") # -- Path setup -------------------------------------------------------------- @@ -131,7 +134,6 @@ def autolog(message): "custom_data_autodoc", "generate_package_rst", ] - # -- panels extension --------------------------------------------------------- # See https://sphinx-panels.readthedocs.io/en/latest/ @@ -165,7 +167,7 @@ def autolog(message): # See https://sphinx-copybutton.readthedocs.io/en/latest/ copybutton_prompt_text = ">>> " -# sphinx.ext.todo configuration +# sphinx.ext.todo configuration ----------------------------------------------- # See https://www.sphinx-doc.org/en/master/usage/extensions/todo.html todo_include_todos = True @@ -228,6 +230,8 @@ def autolog(message): } html_context = { + "rtd_version": rtd_version, + "version": version, "copyright_years": copyright_years, "python_version": build_python_version, # menu_links and menu_links_name are used in _templates/layout.html @@ -296,7 +300,6 @@ def autolog(message): "ignore_pattern": r"__init__\.py", } - # ----------------------------------------------------------------------------- # Remove matplotlib agg warnings from generated doc when using plt.show warnings.filterwarnings( @@ -306,7 +309,6 @@ def autolog(message): " non-GUI backend, so cannot show the figure.", ) - # -- numfig options (built-in) ------------------------------------------------ # Enable numfig. numfig = True diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst index a70385a7ed..538a38da9b 100644 --- a/docs/src/whatsnew/latest.rst +++ b/docs/src/whatsnew/latest.rst @@ -91,6 +91,10 @@ This document explains the changes made to Iris for this release #. `@bjlittle`_ added the |PyPI|_ badge to the `README.md`_. (:pull:`4004`) +#. `@tkknight`_ added a banner at the top of every page of the unreleased + development documentation if being viewed on `Read the Docs`_. + (:pull:`3999`) + 💼 Internal ===========