mkdocs.yml

# MkDocs configuration
# For details see: https://www.mkdocs.org/user-guide/configuration/

# Project information
site_name: "Frequenz Python SDK"
site_description: "A development kit to interact with the Frequenz development platform"
site_author: "Frequenz Energy-as-a-Service GmbH"
copyright: "Copyright © 2022 Frequenz Energy-as-a-Service GmbH"
repo_name: "frequenz-sdk-python"
repo_url: "https://github.com/frequenz-floss/frequenz-sdk-python"
edit_uri: "edit/v1.x.x/docs/"
strict: true  # Treat warnings as errors

# Build directories
theme:
  name: "material"
  logo: _img/logo.png
  favicon: _img/logo.png
  language: en
  icon:
    edit: material/file-edit-outline
    repo: fontawesome/brands/github
  custom_dir: docs/_overrides
  features:
    - content.code.annotate
    - content.code.copy
    - navigation.indexes
    - navigation.instant
    - navigation.footer
    - navigation.tabs
    - navigation.top
    - navigation.tracking
    - toc.follow
  palette:
  - media: "(prefers-color-scheme: light)"
    scheme: default
    primary: indigo
    accent: deep purple
    toggle:
      icon: material/weather-sunny
      name: Switch to dark mode
  - media: "(prefers-color-scheme: dark)"
    scheme: slate
    primary: black
    accent: teal
    toggle:
      icon: material/weather-night
      name: Switch to light mode

extra:
  social:
  - icon: fontawesome/brands/github
    link: https://github.com/frequenz-floss
  - icon: fontawesome/brands/linkedin
    link: https://www.linkedin.com/company/frequenz-com
  version:
    provider: mike
    default: latest

extra_css:
  - _css/style.css
  - _css/mkdocstrings.css

# Formatting options
markdown_extensions:
  - admonition
  - attr_list
  - def_list
  - footnotes
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.keys
  - pymdownx.snippets:
      check_paths: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed
  - pymdownx.tasklist:
      custom_checkbox: true
  - toc:
      permalink: "¤"

plugins:
  - gen-files:
      scripts:
        - docs/_scripts/mkdocstrings_autoapi.py
  - literate-nav:
      nav_file: SUMMARY.md
  - mike:
      alias_type: redirect
      canonical_version: latest
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          options:
            paths: ["src"]
            docstring_section_style: spacy
            inherited_members: true
            merge_init_into_class: false
            separate_signature: true
            show_category_heading: true
            show_root_heading: true
            show_root_members_full_path: true
            show_signature_annotations: true
            show_source: true
            signature_crossrefs: true
          import:
            # See https://mkdocstrings.github.io/python/usage/#import for details
            - https://docs.python.org/3/objects.inv
            - https://frequenz-floss.github.io/frequenz-api-common/v0.3/objects.inv
            - https://frequenz-floss.github.io/frequenz-channels-python/v0.16/objects.inv
            - https://frequenz-floss.github.io/frequenz-api-microgrid/v0.15/objects.inv
            - https://grpc.github.io/grpc/python/objects.inv
            - https://networkx.org/documentation/stable/objects.inv
            - https://numpy.org/doc/stable/objects.inv
            - https://protobuf.readthedocs.io/en/latest/objects.inv
            - https://typing-extensions.readthedocs.io/en/stable/objects.inv
            - https://watchfiles.helpmanual.io/objects.inv
  # Note this plugin must be loaded after mkdocstrings to be able to use macros
  # inside docstrings. See the comment in `docs/_scripts/macros.py` for more
  # details
  - macros:
      module_name: docs/_scripts/macros
      on_undefined: strict
      on_error_fail: true
  - search

# Preview controls
watch:
  - "src"
  - CONTRIBUTING.md