mkdocs.yml

site_name: Input4MIPs validation
site_description: Validation of input4MIPs data (checking file formats, metadata etc.).
site_url: https://input4mips-validation.readthedocs.io
edit_uri: blob/master/docs/

repo_name: climate-resource/input4mips_validation
repo_url: https://github.com/climate-resource/input4mips_validation

nav:
  - Input4MIPs validation: index.md
  - Installation: installation.md
  - How-to guides:
    - how-to-guides/index.md
    - How to write a single valid file: how-to-guides/how-to-write-a-single-valid-file.py
    - How validate a single file: how-to-guides/how-to-validate-a-single-file.py
    - How to write a single file in the DRS: how-to-guides/how-to-write-a-single-file-in-the-drs.py
    - How to upload to an FTP server: how-to-guides/how-to-upload-to-ftp.py
    - How to manage a database of file entries: how-to-guides/how-to-manage-a-database.py
  - Tutorials: tutorials.md
  - Further background:
    - Explanation: explanation.md
  - Command-line interface: cli/index.md
  - API reference: api/input4mips_validation/
  - Development: development.md
  - Changelog: changelog.md

theme:
  name: "material"
  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
  # 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_doc_stubs.py"]
      remove_tag_config:
        remove_input_tags:
          - remove_input
  # Docstring generation
  - mkdocstrings:
      enable_inventory: true
      handlers:
        python:
          paths: [src]
          import:
            # Cross-ref helpers (lots included here, remove what you don't want)
            - https://www.attrs.org/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

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
  # 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: "#"

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