config.yml

copyright: © Russell Keith-Magee

not_in_nav: |
  /index.md
  /about/releases.md

validation:
  omitted_files: warn
  absolute_links: relative_to_docs
  anchors: warn
  unrecognized_links: warn

extra:
  project_name: beeware-docs-tools
  package_name: beeware-docs-tools
  formal_name: "BeeWare Docs Tools"
  website: false  # true shows beeware.org-specific content, false shows project content. Default: false.
  min_python_version: "3.10"  # The oldest supported Python version
  min_python_version_tag: "310"  # The tag version of the minimum python version
  recent_python_version: "3.13"  # The newest Python version known to work on all platforms
  docs_python_version: "3.13"  # The version of Python required to build the documentation
  translated: true  # false hides content related to building translations. Default: false.
  hide_coverage: false  # true hides content related to code coverage. Default: false.
  macos_only: false  # true hides tabbed content, and displays only macOS instructions. Default: false.
  contribution_guide_root: content_test_bed/how-to/contribute
  alternate:
    - name: English
      link: /en/
      lang: en
    - name: العَرَبِيَّة
      link: /ar/
      lang: ar
    - name: Čeština
      link: /cs/
      lang: cs
    - name: Dansk
      link: /da/
      lang: da
    - name: Deutsch
      link: /de/
      lang: de
    - name: Español
      link: /es/
      lang: es
    - name: فارسی
      link: /fa/
      lang: fa
    - name: Français
      link: /fr/
      lang: fr
    - name: Italiano
      link: /it/
      lang: it
    - name: 日本語
      link: /ja/
      lang: ja
    - name: 한국어
      link: /ko/
      lang: ko
    - name: Polski
      link: /pl/
      lang: pl
    - name: Português
      link: /pt/
      lang: pt
    - name: Русский
      link: /ru/
      lang: ru
    - name: தமிழ்
      link: /ta/
      lang: ta
    - name: Türkçe
      link: /tr/
      lang: tr
    - name: Tiếng Việt
      link: /vi/
      lang: vi
    - name: 中文(简体)
      link: /zh_CN/
      lang: zh-Hant
    - name: 中文(繁體)
      link: /zh_TW/
      lang: zh-TW
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/beeware
      name: BeeWare on GitHub
    - icon: fontawesome/brands/mastodon
      link: https://fosstodon.org/@beeware
      name: BeeWare on Mastodon
    - icon: fontawesome/brands/discord
      link: https://beeware.org/bee/chat/
      name: BeeWare on Discord
  generator: false

theme:
  name: material
  language: en
  logo: assets/images/brutus-256.png
  favicon: assets/images/brutus-256.png
  features:
    - content.tabs.link
    - toc.follow
    - navigation.indexes
    - navigation.footer
    - navigation.tabs
    - navigation.tabs.sticky
    - search.suggest
    - search.highlight
    - search.share
  custom_dir: overrides
  palette:
    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to system preference

markdown_extensions:
  # PyMdown Extensions
  pymdownx.fancylists: {}  # Supports various ordered list styles
  pymdownx.highlight: {}  # Highlights code blocks, when language provided.
  pymdownx.inlinehilite: {}  # Highlights inline code, when language provided.
  pymdownx.keys: {}  # Fancy displays key combinations.
  pymdownx.superfences: {}  # Nicer code-blocks.
  pymdownx.saneheaders: {}  # Treats "#Content" with no space at the beginning of a line as text, not a header; helpful with MagicLink. rumdl will still verify header formatting.
  pymdownx.tasklist: {}  # Make fancy checklists.
  pymdownx.blocks.caption: {}  # Captions images.
  pymdownx.blocks.admonition:  # Enables admonitions.
    types:
      - note
      - abstract
      - info
      - tip
      - success
      - question
      - warning
      - failure
      - danger
      - bug
      - example
      - quote
  pymdownx.blocks.details:  # Enables collapsible content.
    types:
      - {name: details-note, class: note}
      - {name: details-abstract, class: abstract}
      - {name: details-info, class: info}
      - {name: details-tip, class: tip}
      - {name: details-success, class: success}
      - {name: details-question, class: question}
      - {name: details-warning, class: warning}
      - {name: details-failure, class: failure}
      - {name: details-danger, class: danger}
      - {name: details-bug, class: bug}
      - {name: details-example, class: example}
      - {name: details-quote, class: quote}
  pymdownx.blocks.tab:  # Enables tabbed content.
    alternate_style: true
  pymdownx.snippets:  # Allows for injecting content from other locations.
    base_path: ["docs"]
    url_download: true
    check_paths: true
  pymdownx.magiclink:  # Among other things, enables GitHub shorthand references.
    provider: "github"
    user: "beeware"
    repo: "website"
    repo_url_shortener: true
    repo_url_shorthand: true
    normalize_issue_symbols: true
  # Python Markdown Extensions
  attr_list: {}  # Enables setting explicit anchors, and CSS classes, etc.
  smarty:  # Enables easy em and en dashes.
    smart_quotes: false
  toc:  # Enables the ToC, in the left sidebar, in the documentation.
    permalink: true
    title: On this page

plugins:
  search: {}
  autorefs:
    resolve_closest: true  # autorefs warns of the Usage headings begin duplicates without this - we will have to assign unique ids to all of them otherwise
  literate-nav:
    nav_file: SUMMARY.md
  macros:
    include_dir: {}
  mkdocstrings:
    default_handler: python
    handlers:
      python:
        paths: [src]
        options:
          docstring_style: sphinx  # Parses docstrings from Sphinx formatting - the `:param` formatting, not parsing rST links
          allow_inspection: false  # True includes *more* dunder methods, can be enabled on individual class entries if you want them
          show_source: false  # Otherwise, source code is shown collapsed for all
          members_order: alphabetical  # Orders things based on the source code
          annotations_path: brief  # Keeps type annotation links more concise
          merge_init_into_class: true  # Otherwise, init is displayed separately
          separate_signature: true  # Shows the `function(args)` separately from name
          show_signature: true  # Displays () or (args) along with the function name in the signature
          show_signature_annotations: true  # Includes annotations in signature blocks
          signature_crossrefs: true  # Enables cross-referencing on signature annotations
          show_root_heading: true  # Show heading of object at root, otherwise nothing
          docstring_section_style: spacy  # Better info layout than the other options
          line_length: 80  # Requires ruff, forces longer signatures to be stacked
          show_symbol_type_toc: true  # Enables type symbols next to objects in ToC
          show_symbol_type_heading: true  # Enables type symbols next to object names in content
          show_attribute_values: false  # Suppresses the values of attributes in the signature
          heading_level: 3  # Heading level of 3 to nest under References heading