diff --git a/doc/_templates/cross_proj_navbar.html b/doc/_templates/cross_proj_navbar.html new file mode 100644 index 0000000000..11d6b281c8 --- /dev/null +++ b/doc/_templates/cross_proj_navbar.html @@ -0,0 +1,25 @@ +{% set href = pathto(root_doc) %} + diff --git a/doc/_templates/sidebar_nav_lv1.html b/doc/_templates/sidebar_nav_lv1.html new file mode 100644 index 0000000000..d5e4c84809 --- /dev/null +++ b/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 #} + diff --git a/doc/conf.py b/doc/conf.py index 3d5bf9d9d3..9279513182 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -183,6 +183,9 @@ "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)", + # "content_footer_items" : ["footer_custom"], } # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] @@ -222,7 +225,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. @@ -502,8 +507,3 @@ } # -- Custom Document processing ---------------------------------------------- - -sys.path.append(os.path.dirname(__file__)) -from gensidebar import generate_sidebar - -generate_sidebar(globals(), "esmvalcore") diff --git a/doc/figures/ESMValSchemaDiagram.png b/doc/figures/ESMValSchemaDiagram.png new file mode 100644 index 0000000000..f32a461922 Binary files /dev/null and b/doc/figures/ESMValSchemaDiagram.png differ diff --git a/doc/gensidebar.py b/doc/gensidebar.py deleted file mode 100644 index 1b181b481d..0000000000 --- a/doc/gensidebar.py +++ /dev/null @@ -1,85 +0,0 @@ -"""Generates sidebar/toctree. - -Generates the common sidebar/toctree for the sphinx/ReadTheDocs -documentation of the ESMValTool and its subprojects. -""" - -import os - - -def _write_if_changed(fname, contents): - """Write/update file only if changed.""" - try: - with open(fname, encoding="utf-8") as stream: - old_contents = stream.read() - except OSError: - old_contents = "" - - if old_contents != contents: - with open(fname, "w", encoding="utf-8") as stream: - stream.write(contents) - - -def generate_sidebar(conf, conf_api): - """Generate sidebar. - - Generate sidebar for ReadTheDocs with links to subprojects and - superprojects accordingly. - """ - # determine 'latest' or 'stable' - # if not conf.do_gen: - do_gen = os.environ.get("SIDEBAR", None) == "1" or conf["on_rtd"] - - lines = ["", ".. DO NOT MODIFY! THIS PAGE IS AUTOGENERATED!", ""] - - def _toctree(): - lines.extend([".. toctree::", " :maxdepth: 1", ""]) - - def _endl(): - lines.append("") - - def _write(project, desc, link, mapping=conf["intersphinx_mapping"]): - if project != conf_api: - if do_gen: - args = desc, mapping[project][0], link - lines.append(" {} <{}{}.html>".format(*args)) - else: - args = desc, link - lines.append(" {} <{}>".format(*args)) - - def _header(project, text): - if project == conf_api or do_gen: - lines.extend([".. toctree::", " :maxdepth: 2"]) - lines.extend([f" :caption: {text}", ""]) - - # - # Specify the sidebar contents here - # - - _header("esmvaltool", "ESMValTool") - _write("esmvaltool", "Introduction", "introduction") - _write("esmvaltool", "ESMValTool Functionalities", "functionalities") - _write("esmvaltool", "Getting started", "quickstart/index") - _write("esmvaltool", "Gallery", "gallery") - _write("esmvaltool", "Available recipes", "recipes/index") - _write("esmvaltool", "Obtaining input data", "input") - _write("esmvaltool", "Making a recipe or diagnostic", "develop/index") - _write("esmvaltool", "Contributing to the community", "community/index") - _write("esmvaltool", "Utilities", "utils") - _write("esmvaltool", "Diagnostics API Reference", "api/esmvaltool") - _write("esmvaltool", "Frequently Asked Questions", "faq") - _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)) diff --git a/doc/index.rst b/doc/index.rst index e4bb98a9d2..c35794b193 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,13 +1,40 @@ -Welcome to ESMValTool's documentation! +:html_theme.sidebar_secondary.remove: + +Welcome to ESMValCore'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 `_ and `ESMValTool: Recipes for solid climate science `_. -A tutorial is available on https://tutorial.esmvaltool.org. + +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. +ESMValCore can be used without ESMValTool such as in a Jupyter notebook. +For more detailed information, see documentation navigation to the left. Please also see +`ESMValTool documentation `_. + +.. container:: + :name: figarch + + .. figure:: figures/ESMValSchemaDiagram.png + :alt: Brief topics for tool and core. + :class: dark-light + + +Learning resources: +------------------- + +A carpentries tutorial is available on https://tutorial.esmvaltool.org. A series of video lectures has been created by `ACCESS-NRI `_. While these are tailored for ACCESS users, they are still very informative. @@ -16,16 +43,32 @@ While these are tailored for ACCESS users, they are still very informative. -| +How to contribute +----------------- +Refer to ESMValTool contributing to the community for a guide on contributing recipes and diagnostics. + +Refer to ESMValCore :ref:`Contributing ` for information on contributing code. -For more detailed information, the documentation is available below. +Get in touch! +------------- +Contact information is available :ref:`here `. -Get in touch! Contact information is available :ref:`here `. +.. toctree:: + :hidden: + :maxdepth: 2 + :caption: ESMValCore -.. include:: _sidebar.rst.inc + Getting started + Example notebooks + The recipe format + Diagnostic script interfaces + Development + Contributing + ESMValCore API Reference + Changelog Indices and tables -================== +------------------ * :ref:`genindex` * :ref:`search`