mkdocs.yml

site_name: Climate REF
site_description: The Rapid Evaluation Framework for near-real time evaluation of climate models
site_url: https://climate-ref.readthedocs.io
edit_uri: blob/master/docs/

repo_name: Climate-REF/climate-ref
repo_url: https://github.com/Climate-REF/climate-ref

nav:
  - Rapid Evaluation Framework: index.md
  - Installation: installation.md
  - In a Nutshell: nutshell.md
  - Getting Started:
      - Configure: getting-started/01-configure.md
      - Download Datasets: getting-started/02-download-datasets.md
      - Ingest: getting-started/03-ingest.md
      - Solve: getting-started/04-solve.md
      - Visualise: getting-started/05-visualise.md
  - Configuration: configuration.md
  - Diagnostics:
      - diagnostics/index.md
      - Example: diagnostics/example.md
      - ESMValTool: diagnostics/esmvaltool.md
      - PMP: diagnostics/pmp.md
      - ILAMB: diagnostics/ilamb.md
  - Roadmap: roadmap.md
  - How-to guides:
      - how-to-guides/index.md
      - how-to-guides/using-pre-computed-results.py
      - how-to-guides/executors.md
      - how-to-guides/hpc_executor.md
      - how-to-guides/dataset-selection.py
      - how-to-guides/ingest-datasets.md
      - how-to-guides/running-diagnostics-locally.py
      - how-to-guides/adding_custom_diagnostics.md
      - how-to-guides/testing-diagnostics.md
      - how-to-guides/docker_deployment.md
  - Further background:
      - Basic Concepts: background/basic-concepts.md
      - Architecture: background/architecture.md
      - Explanation: background/explanation.md
      - Datasets: background/datasets.md
      - API Surface: api-surface.md
      - Versioning and Compatibility: versioning-and-compatibility.md
  - CLI: cli.md
  - API: api/
  - Development: development.md
  - Changelog: changelog.md

theme:
  name: "material"
  favicon: images/favicon.svg
  features:
    - content.code.copy
  custom_dir: docs/overrides
  palette:
    # Light mode (toggle to dark mode)
    - scheme: cr-light
      primary: teal
      accent: cyan
      toggle:
        icon: material/weather-night
        name: Switch to dark mode

    # Dark mode (toggle back to light mode)
    - scheme: cr-dark
      primary: teal
      accent: cyan
      toggle:
        icon: material/brightness-7
        name: Switch to light mode

extra_css:
  - stylesheets/style.css

plugins:
  # https://mkdocstrings.github.io/autorefs/
  - autorefs
  # Required for auto-generating our documentation stubs
  # https://oprypin.github.io/mkdocs-gen-files/
  - gen-files:
      scripts:
        - docs/gen_doc_stubs.py
        - docs/gen_config_stubs.py
        - docs/gen_diagnostic_stubs.py
  # Make the navigation easier to handle/auto-generate if we wish
  # https://oprypin.github.io/mkdocs-literate-nav/
  - literate-nav:
      nav_file: NAVIGATION.md
  # Notebook support.
  # Working out how to make this play with nb-exec would be nice,
  # then it wouldn't run every time.
  # See also: https://github.com/danielfrg/mkdocs-jupyter/issues/161
  # We could also get the nb-exec-table mentioned here:
  # https://myst-nb.readthedocs.io/en/v0.12.2/use/execute.html
  # One for another day.
  - mkdocs-jupyter:
      # Use filenames for titles
      ignore_h1_titles: True
      include: ["*.py"]
      execute: true
      # Toggle off for faster builds
      # execute: false
      allow_errors: false
      # theme: dark
      include_source: True
      ignore: ["*.ipynb", "*.md", "docs/gen_*.py"]
      remove_tag_config:
        remove_cell_tags:
          - remove_cell
        remove_input_tags:
          - remove_input
        remove_single_output_tags:
          - remove_output
        remove_all_outputs_tags:
          - remove_output
  # Docstring generation
  - mkdocstrings:
      enable_inventory: true
      handlers:
        python:
          paths: [packages]
          inventories:
            # Cross-climate_ref helpers (lots included here, remove what you don't want)
            - https://www.attrs.org/en/stable/objects.inv
            - https://catt.rs/en/stable/objects.inv
            - https://unidata.github.io/cftime/objects.inv
            - https://ipython.readthedocs.io/en/stable/objects.inv
            - https://loguru.readthedocs.io/en/latest/objects.inv
            - https://matplotlib.org/stable/objects.inv
            - https://ncdata.readthedocs.io/en/stable/objects.inv
            - https://openscm-units.readthedocs.io/en/stable/objects.inv
            - https://pandas.pydata.org/docs/objects.inv
            - https://pint.readthedocs.io/en/stable/objects.inv
            - https://www.fatiando.org/pooch/latest/objects.inv
            - https://docs.python.org/3/objects.inv
            - https://docs.scipy.org/doc/scipy/objects.inv
            - https://scitools-iris.readthedocs.io/en/stable/objects.inv
            - https://scmdata.readthedocs.io/en/stable/objects.inv
            - https://validators.readthedocs.io/en/stable/objects.inv
            - http://xarray.pydata.org/en/stable/objects.inv
          options:
            docstring_style: numpy
            show_root_heading: true
            show_source: true
  # https://squidfunk.github.io/mkdocs-material/plugins/search/
  - search
  # https://oprypin.github.io/mkdocs-section-index/
  - section-index
  # https://github.com/PLAYG0N/mkdocs-panzoom
  - panzoom:
      full_screen: true

markdown_extensions:
  # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#attribute-lists
  - attr_list
  # Allow admonitions, useful for deprecation warnings
  # https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/admonition/
  - pymdownx.blocks.admonition
  # Allow captions on blocks
  # https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/caption/
  - pymdownx.blocks.caption
  # Code highlighting handiness
  # https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  # https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
  - pymdownx.inlinehilite
  # Enable the use of snippets (e.g. taking snippets from README and putting them in docs)
  # https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
  - pymdownx.snippets
  # Support more complicated indents etc.
  # https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
  - pymdownx.superfences
  # Tabbed sections (e.g. for our installation options)
  # https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
  - pymdownx.tabbed:
      alternate_style: true
  # Support tables (used in our API docs)
  # https://squidfunk.github.io/mkdocs-material/reference/data-tables/
  - tables
  # Ensure that there are links to table of contents items
  - toc:
      permalink: "#"
  # Support for mermaid diagrams
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
            # yamllint disable-line
            # https://github.com/mkdocs/mkdocs-click


  - mkdocs-typer:

watch:
  - README.md
  # Auto-generate if `src` changes (because this changes API docs)
  - packages