Documentation homepage, use of panels for visibility to users

docs/iris/src/common_links.inc

@@ -24,3 +24,4 @@
 .. _conda: https://docs.conda.io/en/latest/
 .. _sphinx: https://www.sphinx-doc.org/en/master/
 .. _napolean: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html
+.. _legacy documentation: https://scitools.org.uk/iris/docs/v2.4.0/

docs/iris/src/conf.py

@@ -115,6 +115,7 @@ def autolog(message):
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
     "sphinx.ext.napoleon",
+    "sphinx_panels",
     # TODO: Spelling extension disabled until the dependencies can be included
     # "sphinxcontrib.spelling",
     "sphinx_gallery.gen_gallery",
@@ -126,6 +127,9 @@ def autolog(message):
     "generate_package_rst",
 ]
 
+# -- panels extension ---------------------------------------------------------
+# See https://sphinx-panels.readthedocs.io/en/latest/
+
 # -- Napoleon extension -------------------------------------------------------
 # See https://sphinxcontrib-napoleon.readthedocs.io/en/latest/sphinxcontrib.napoleon.html
 napoleon_google_docstring = True

docs/iris/src/developers_guide/contributing_getting_involved.rst

@@ -1,7 +1,7 @@
-.. _development_where_to_start:
-
 .. include:: ../common_links.inc
 
+.. _development_where_to_start:
+
 Getting Involved
 ----------------
 

docs/iris/src/index.rst

@@ -1,9 +1,3 @@
-.. note:: For **Iris 2.4** and earlier documentation please see the
-          `legacy documentation`_
-
-.. _legacy documentation: https://scitools.org.uk/iris/docs/v2.4.0/
-
-
 Iris Documentation
 ==================
 
@@ -44,11 +38,61 @@ Interoperability with packages from the wider scientific Python ecosystem comes
 from Iris' use of standard NumPy/dask arrays as its underlying data storage.
 
 Iris is part of SciTools, for more information see https://scitools.org.uk/.
+For **Iris 2.4** and earlier documentation please see the
+:link-badge:`https://scitools.org.uk/iris/docs/v2.4.0/,"legacy documentation",cls=badge-info text-white`.
+
+
+.. panels::
+    :container: container-lg pb-3
+    :column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2
+
+    Install Iris to use or for development.
+    +++
+    .. link-button:: installing_iris
+        :type: ref
+        :text: Installing Iris
+        :classes: btn-outline-primary btn-block
+    ---
+    Example code to create a variety of plots.
+    +++
+    .. link-button:: sphx_glr_generated_gallery
+        :type: ref
+        :text: Gallery
+        :classes: btn-outline-primary btn-block
+    ---
+    Find out what has recently changed in Iris.
+    +++
+    .. link-button:: iris_whatsnew
+        :type: ref
+        :text: What's New
+        :classes: btn-outline-primary btn-block
+    ---
+    Learn how to use Iris.
+    +++
+    .. link-button:: user_guide_index
+        :type: ref
+        :text: User Guide
+        :classes: btn-outline-primary btn-block
+    ---
+    Browse full Iris functionality by module.
+    +++
+    .. link-button:: Iris
+        :type: ref
+        :text: Iris API
+        :classes: btn-outline-primary btn-block
+    ---
+    As a developer you can contribute to Iris.
+    +++
+    .. link-button:: development_where_to_start
+        :type: ref
+        :text: Getting Involved
+        :classes: btn-outline-primary btn-block
 
 
 .. toctree::
    :maxdepth: 1
    :caption: Getting started
+   :hidden:
 
    installing
    generated/gallery/index
@@ -58,6 +102,7 @@ Iris is part of SciTools, for more information see https://scitools.org.uk/.
    :maxdepth: 1
    :caption: User Guide
    :name: userguide_index
+   :hidden:
 
    userguide/index
    userguide/iris_cubes
@@ -81,20 +126,22 @@ Iris is part of SciTools, for more information see https://scitools.org.uk/.
    :maxdepth: 1
    :caption: Developers Guide
    :name: development_index
+   :hidden:
 
    developers_guide/contributing_getting_involved
    developers_guide/gitwash/index
    developers_guide/contributing_documentation
    developers_guide/contributing_codebase_index
    developers_guide/contributing_changes
    developers_guide/release
-   generated/api/iris
 
 
 .. toctree::
    :maxdepth: 1
    :caption: Reference
+   :hidden:
 
+   generated/api/iris
    whatsnew/index
    techpapers/index
    copyright

requirements/ci/py36.yml

@@ -49,3 +49,5 @@ dependencies:
   - pip
   - pip:
     - sphinxcontrib-napoleon
+    - sphinx-panels
+

requirements/ci/py37.yml

@@ -49,3 +49,4 @@ dependencies:
   - pip
   - pip:
     - sphinxcontrib-napoleon
+    - sphinx-panels

requirements/docs.txt

@@ -5,3 +5,4 @@ sphinx-copybutton
 sphinx-gallery
 sphinx_rtd_theme
 sphinxcontrib-napoleon
+sphinx-panels