mkdocs.yml

# Project information
site_name: Acoustic-Toolbox
site_description: Documentation for the acoustic-toolbox project

site_dir: build/html
# Set the site URL by using a Read the Docs environment variable:
# https://docs.readthedocs.io/en/stable/reference/environment-variables.html
site_url: !ENV READTHEDOCS_CANONICAL_URL

# Repository
repo_name: acoustic-toolbox
repo_url: https://github.com/Universite-Gustave-Eiffel/acoustic-toolbox
edit_uri: edit/main/example/docs

# Copyright
copyright: Copyright © 2024, Valentin LE BESCOND, Andrew Mitchell

# Configuration
theme:
  name: material
  language: en
  logo: images/logo_txt.png
  # favicon: assets/images/geoserver_mark.png

  # https://squidfunk.github.io/mkdocs-material/customization/
  custom_dir: docs/overrides

  palette:
    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: blue
      toggle:
        icon: material/weather-night
        name: Switch to dark mode
    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode
  features:
    # From setup template I used - can remove if not needed
    - content.action.view
    - content.action.edit
    - content.code.copy
    - content.tabs.link
    - navigation.tracking
    - navigation.tabs
    - navigation.prune
    - navigation.indexes
    - toc.follow
    - navigation.top
    - navigation.footer
    - announce.dismiss

# Plugins - install using: pip3 install -r requirements.txt
plugins:
  - search
  - mkdocs-jupyter:
      ignore_h1_titles: True
      include_source: True
  - autorefs:
      resolve_closest: true
  - mkdocstrings: # For building API ref from docstrings https://mkdocstrings.github.io/usage/#docsmy_pagemd
      enable_inventory: true
      handlers:
        python:
          inventories:
            - https://docs.python.org/3/objects.inv
            - https://docs.scipy.org/doc/scipy/objects.inv
            - https://numpy.org/doc/stable/objects.inv
            - https://pandas.pydata.org/docs/objects.inv
            - https://matplotlib.org/stable/objects.inv
          options:
            # Docstring styling
            # https://mkdocstrings.github.io/python/usage/configuration/general/
            docstring_style: google # Need to update sphinx docstrings to google style
            docstring_section_style: spacy
            show_root_members_full_path: false
            members_order: source
            merge_init_into_class: true
            # Signature styling
            separate_signature: true
            show_signature_annotations: true
            signature_crossrefs: true
            # modernize_annotations: true
            line_length: 60

            # Toc styling
            show_root_toc_entry: false
            show_symbol_type_heading: true
            show_symbol_type_toc: true
            group_by_category: true
            show_category_heading: true
            docstring_options:
              ignore_init_summary: true
              trim_doctest_flags: true
              warn_unknown_params: false

  # From setup template I used - can remove if not needed
  - exclude:
      glob:
        - "**/download/download.txt"
  - include-markdown:
      preserve_includer_indent: true
      dedent: true
      comments: false
  - macros:
      render_by_default: false
      on_error_fail: true
      on_undefined: strict
      j2_block_start_string: "[[%"
      j2_block_end_string: "%]]"

# Customizations
extra:
  homepage: https://github.com/Universite-Gustave-Eiffel/acoustic-toolbox
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/Universite-Gustave-Eiffel/acoustic-toolbox
  version:
    provider: mike # https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#versioning
  release: "0.9.5"

# Include extra CSS to make some style adjustments
extra_css:
  - stylesheets/readthedocs.css
  - https://unpkg.com/katex@0/dist/katex.min.css # enable KaTeX support

# Include extra JS to setup Read the Docs addons integrations
extra_javascript:
  - javascripts/readthedocs.js
  - javascripts/katex.js # enable KaTeX support
  - https://unpkg.com/katex@0/dist/katex.min.js # enable KaTeX support
  - https://unpkg.com/katex@0/dist/contrib/auto-render.min.js # enable KaTeX support

# Extensions
# - These are carefully chosen to work with pandoc markdown support for whole document translation
markdown_extensions:
  - pymdownx.arithmatex: # enable KaTeX support https://squidfunk.github.io/mkdocs-material/reference/math/#katex
      generic: true
  - tables

  # From setup template I used - can remove if not needed
  - admonition
  - attr_list
  - def_list
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - md_in_html

# Validation
validation:
  nav:
    omitted_files: info
    not_found: warn
    absolute_links: info
  links:
    not_found: warn
    absolute_links: info
    unrecognized_links: info

not_in_nav: |
  **/download/*.md

# Page tree
nav:
  - Home: index.md
  - Examples:
      - Overview: examples.md
      - Signal Class: examples/signal_class.ipynb
      - Directivity: examples/directivity_example.ipynb
      - Octave: examples/example_octave.py
      - Signal Processing: examples/example_signal.py
  - Signal Class: _signal.md
  - Modules:
      - Ambisonics: ambisonics.md
      - Atmosphere: atmosphere.md
      - Bands: bands.md
      - Building: building.md
      - Cepstrum: cepstrum.md
      - Criterion: criterion.md
      - Decibel: decibel.md
      - Descriptors: descriptors.md
      - Directivity: directivity.md
      - Doppler: doppler.md
      - Generator: generator.md
      - Imaging: imaging.md
      - Octave: octave.md
      - Power: power.md
      - Quantity: quantity.md
      - Reflection: reflection.md
      - Room Acoustics: room.md
      - Signal Processing: signal.md
      - Utilities: utils.md
      - Weighting: weighting.md
  - Standards:
      - Standards Overview: standards.md
      - IEC 61260-1:2014: standards/iec_61260_1_2014.md
      - IEC 61672-1:2013: standards/iec_61672_1_2013.md
      - ISO 1683:2015: standards/iso_1683_2015.md
      - ISO 1996-1:2003: standards/iso_1996_1_2003.md
      - ISO 1996-2:2007: standards/iso_1996_2_2007.md
      - ISO 9613-1:1993: standards/iso_9613_1_1993.md
      - ISO/TR 25417:2007: standards/iso_tr_25417_2007.md