Documentation layout to highlight 2 packages

doc/_templates/cross_proj_navbar.html

@@ -0,0 +1,32 @@
+{# Displays links to the top-level TOCtree elements, in the header navbar. #}
+{% set href = pathto(root_doc) %}
+<nav>
+  <ul class="bd-navbar-elements navbar-nav">
+    {# { generate_header_nav_html(n_links_before_dropdown=theme_header_links_before_dropdown, dropdown_text=theme_header_dropdown_text) } #}
+        <li class="nav-item ">
+            <a class="nav-link nav-external" href="https://docs.esmvaltool.org/en/latest/index.html">
+             ESMValTool
+            </a>
+        </li>
+        <li class="nav-item current active">
+            <a class="nav-link nav-internal" href="{{ href }}">
+            {{ (" ESMValCore ") }}
+            </a>
+        </li>
+        <li class="nav-item ">
+            <a class="nav-link nav-external" href="{{ href }}/gallery">
+            Gallery
+            </a>
+        </li>
+        <li class="nav-item ">
+            <a class="nav-link nav-external" href="https://tutorial.esmvaltool.org/">
+            Tutorial
+            </a>
+        </li>
+        <li class="nav-item ">
+            <a class="nav-link nav-external" href="https://esmvaltool.org/">
+            Web site
+            </a>
+        </li>
+  </ul>
+</nav>

doc/_templates/sidebar_nav_lv1.html

@@ -0,0 +1,17 @@
+{# Displays the TOC-subtree for pages nested under the currently active top-level TOCtree element. EDITED #}
+<nav class="bd-docs-nav bd-links"
+     aria-label="{{ _('Section Navigation') }}">
+  <p class="bd-links__title" role="heading" aria-level="1">{{ _("Documentation Navigation") }}</p>
+  <div class="bd-toc-item navbar-nav">
+    {{- generate_toctree_html(
+      startdepth=0,
+      kind="sidebar",
+      show_nav_level=theme_show_nav_level | int,
+      maxdepth=theme_navigation_depth | int,
+      collapse=theme_collapse_navigation | tobool,
+      includehidden=theme_sidebar_includehidden | tobool,
+      titles_only=True
+      )
+    -}}
+  </div>
+</nav>

doc/conf.py

@@ -180,6 +180,8 @@
         "image_light": "figures/ESMValTool-logo-2.png",
         "image_dark": "figures/ESMValTool-logo-2-dark.png",
     },
+    "navbar_center": ["cross_proj_navbar"],
+    "search_bar_text": "Search docs... (hint: also try search in ESMValTool docs)",
 }
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -219,7 +221,9 @@
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+html_sidebars = {
+    "**": ["sidebar_nav_lv1", "sidebar-ethical-ads"]
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

doc/gensidebar.py

@@ -2,6 +2,7 @@
 
 Generates the common sidebar/toctree for the sphinx/ReadTheDocs
 documentation of the ESMValTool and its subprojects.
+Swap order so that ESMValCore is at the top for ESMValCore documentation.
 """
 
 import os
@@ -56,6 +57,17 @@ def _header(project, text):
     # Specify the sidebar contents here
     #
 
+    _header("esmvalcore", "ESMValCore")
+    _write("esmvalcore", "Getting started", "quickstart/index")
+    _write("esmvalcore", "Example notebooks", "example-notebooks")
+    _write("esmvalcore", "The recipe format", "recipe/index")
+    _write("esmvalcore", "Diagnostic script interfaces", "interfaces")
+    _write("esmvalcore", "Development", "develop/index")
+    _write("esmvalcore", "Contributing", "contributing")
+    _write("esmvalcore", "ESMValCore API Reference", "api/esmvalcore")
+    _write("esmvalcore", "Changelog", "changelog")
+    _endl()
+
     _header("esmvaltool", "ESMValTool")
     _write("esmvaltool", "Introduction", "introduction")
     _write("esmvaltool", "ESMValTool Functionalities", "functionalities")
@@ -71,15 +83,4 @@ def _header(project, text):
     _write("esmvaltool", "Changelog", "changelog")
     _endl()
 
-    _header("esmvalcore", "ESMValCore")
-    _write("esmvalcore", "Getting started", "quickstart/index")
-    _write("esmvalcore", "Example notebooks", "example-notebooks")
-    _write("esmvalcore", "The recipe format", "recipe/index")
-    _write("esmvalcore", "Diagnostic script interfaces", "interfaces")
-    _write("esmvalcore", "Development", "develop/index")
-    _write("esmvalcore", "Contributing", "contributing")
-    _write("esmvalcore", "ESMValCore API Reference", "api/esmvalcore")
-    _write("esmvalcore", "Changelog", "changelog")
-    _endl()
-
     _write_if_changed("_sidebar.rst.inc", "\n".join(lines))

doc/index.rst

@@ -1,12 +1,35 @@
 Welcome to ESMValTool's documentation!
 ======================================
 
+**ESMValTool** is a community diagnostics and performance metrics tool for the evaluation of Earth System Models (ESMs) that allows for
+routine comparison of models and observations. It includes a large collection of community recipes and observation data formatters to CMOR standards.
+
+**ESMValCore** is a software package which provides the core functionality for ESMValTool. It is a workflow to find CMIP data, and apply
+commonly used pre-processing functions.
+
 To get a first impression of what ESMValTool and ESMValCore can do for you,
 have a look at our blog posts
 `Analysis-ready climate data with ESMValCore <https://blog.esciencecenter.nl/easy-ipcc-powered-by-esmvalcore-19a0b6366ea7>`_
 and
 `ESMValTool: Recipes for solid climate science <https://blog.esciencecenter.nl/esmvaltool-recipes-for-solid-climate-science-da5b33814f69>`_.
 
+
+Basic documentation schema
+--------------------------
+This gives a brief idea of topics in each of the packages to help find information. As ESMValTool encompasses ESMValCore there will be some overlap between them.
+For more detailed information, see documentation navigation to the left.
+
+.. container::
+   :name: figarch
+
+   .. figure:: figures/ESMValSchemaDiagram.png
+      :alt: Brief topics for tool and core.
+      :figclass: align-center
+
+
+Learning resources:
+-------------------
+
 A tutorial is available on https://tutorial.esmvaltool.org.
 
 A series of video lectures has been created by `ACCESS-NRI <https://access-nri.org.au>`_.
@@ -16,13 +39,29 @@ While these are tailored for ACCESS users, they are still very informative.
 
    <iframe width="560" height="315" src="https://www.youtube.com/embed/videoseries?si=pUXrXB8C8bLRfQHY&amp;list=PLFjfi2xLaFpJp59LvDc1upQsj_xzFlFLc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
-|
+How to contribute
+-----------------
+Refer to ESMValTool contributing to the community for a guide on contributing recipes and diagnostics.
+
+Refer to ESMValCore :ref:`Contributing <contributing>`  for information on contributing code.
 
-For more detailed information, the documentation is available below.
+Get in touch!
+-------------
+Contact information is available :ref:`here <Support-and-Contact>`.
 
-Get in touch! Contact information is available :ref:`here <Support-and-Contact>`.
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: ESMValCore
 
-.. include:: _sidebar.rst.inc
+    Getting started <quickstart/index>
+    Example notebooks <example-notebooks>
+    The recipe format <recipe/index>
+    Diagnostic script interfaces <interfaces>
+    Development <develop/index>
+    Contributing <contributing>
+    ESMValCore API Reference <api/esmvalcore>
+    Changelog <changelog>
 
 Indices and tables
 ==================