mkdocs.yml

site_name: Bookshelf
site_description: Curated set of climate data
site_url: https://climate-resource.github.io/bookshelf
edit_uri: blob/master/docs/

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

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

# Enable versioned doc builds
# Using {major}.{minor}, latest and dev releases
extra:
  version:
    provider: mike

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, packages/bookshelf-producer/src]
          import:
            # Cross-ref helpers (lots included here, remove what you don't want)
            - https://www.attrs.org/en/stable/objects.inv
            - https://ipython.readthedocs.io/en/stable/objects.inv
            - https://matplotlib.org/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://scmdata.readthedocs.io/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/byrnereese/mkdocs-minify-plugin
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
  # https://github.com/jimporter/mike
  - mike:
      alias_type: copy

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 `packages` changes (because this changes API docs)
  - packages