mkdocs.yml

theme:  # pulled from optimistix
    name: material
    features:
        - navigation.sections  # Sections are included in the navigation on the left.
        - toc.integrate  # Table of contents is integrated on the left; does not appear separately on the right.
        - header.autohide  # header disappears as you scroll
    palette:
        # Light mode / dark mode
        # We deliberately don't automatically use `media` to check a user's preferences. We default to light mode as
        # (a) it looks more professional, and (b) is more obvious about the fact that it offers a (dark mode) toggle.
        - scheme: default
          primary: white
          accent: amber
          toggle:
             icon: material/weather-night
             name: Switch to dark mode
        - scheme: slate
          primary: black
          accent: amber
          toggle:
             icon: material/weather-sunny
             name: Switch to light mode
    icon:
        repo: fontawesome/brands/github               # GitHub logo in top right
        logo: "material/sigma"                        # traceax logo in top left
    favicon: "_static/favicon.png"
    custom_dir: "docs/_overrides"  # Overriding part of the HTML


site_name: Traceax
site_description: The documentation for the traceax software library.
site_url: https://mancusolab.github.io/traceax

repo_url: https://github.com/mancusolab/traceax
repo_name: mancusolab/traceax
edit_uri: ""  # No edit button, as some of our pages are in /docs and some in /examples via symlink, so it's impossible for them all to be accurate

strict: true  # Don't allow warnings during the build process

extra_javascript:
    # The below three make MathJax work, see https://squidfunk.github.io/mkdocs-material/reference/mathjax/
    - _static/mathjax.js
    - https://polyfill.io/v3/polyfill.min.js?features=es6
    - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

extra_css:
    - _static/custom_css.css

markdown_extensions:
    - pymdownx.arithmatex:      # Render LaTeX via MathJax
        generic: true
    - pymdownx.superfences      # Seems to enable syntax highlighting when used with the Material theme.
    - pymdownx.details          # Allowing hidden expandable regions denoted by ???
    - pymdownx.snippets:        # Include one Markdown file into another
        base_path: docs
    - admonition
    - toc:
        permalink: "¤"  # Adds a clickable permalink to each section heading
        toc_depth: 4

plugins:
    - search    # default search plugin; needs manually re-enabling when using any other plugins
    - autorefs  # Cross-links to headings
    - include_exclude_files:
        exclude:
            - "_overrides"
    - mkdocstrings:
        default_handler: python
        enable_inventory: true
        custom_templates: docs/templates
        handlers:
            python:
                paths: [src]
                import:
                - https://docs.kidger.site/equinox/objects.inv
                - https://docs.kidger.site/jaxtyping/objects.inv
                setup_commands:
                    - import jaxtyping
                    - jaxtyping.set_array_name_format("array")
                    - import typing
                    - typing.Any.__module__ = "builtins"
                load_external_modules: true
                options:
                    preload_modules:
                    - equinox
                    - jaxtyping
                    extensions:
                    - pydantic: {schema: true}
                    - docs/scripts/extension.py:DynamicDocstrings:
                        paths: [ traceax._estimators, traceax._samplers ]
                    # general options
                    allow_inspection: true
                    show_bases: true
                    show_source: false
                    # heading options
                    heading_level: 4
                    show_root_heading: true
                    show_root_full_path: true
                    # members options
                    inherited_members: true
                    members_order: source
                    filters:
                        - "!^_"
                        - "^__init__$"
                    # docstring options
                    show_if_no_docstring: true
                    # signature/type annotation options
                    separate_signature: false
                    annotations_path: brief
                    show_signature_annotations: true

nav:
    - 'index.md'
    - API:
      - 'api/estimators.md'
      - 'api/samplers.md'
    - Misc:
        - 'authors.md'
        - 'license.md'
        - 'conduct.md'