mkdocs.yml

site_name: Research Project Template (preview)
site_description: Template for a ML Research project.
# TODO: Need to make sure that the repo URL and site URL are updated correctly in downstream
# projects, otherwise they will either get a 403 error, or change the docs of the template!
site_url: https://mila-iqia.github.io/ResearchTemplate/
repo_url: https://www.github.com/mila-iqia/ResearchTemplate
# edit_uri: edit/master/docs

extra_css:
  - extra.css

theme:
  name: material
  features:
    - toc.follow
    - toc.integrate
    - navigation.instant
    # - navigation.indexes
    # - navigation.path
    # - navigation.expand
    # - navigation.tabs
    # - navigation.tabs.sticky
    - navigation.instant.prefetch
    - navigation.instant.preview
    - content.code.copy
    - navigation.tracking
  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:
  - toc:
      permalink: "#"
      toc_depth: 3
  - pymdownx.highlight: # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#configuration
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences
  - pymdownx.magiclink
  - attr_list
  - md_in_html
  - admonition
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower

plugins:
  - search
  - awesome-pages
  - macros: #https://mkdocs-macros-plugin.readthedocs.io/en/latest/#declaration-of-the-macros-plugin
      module_name: docs/macros
  - custom_autoref_plugin
  - autorefs
  - gen-files:
      # https://oprypin.github.io/mkdocs-gen-files/#usage
      scripts:
        - docs/generate_reference_docs.py
  - literate-nav:
      nav_file: SUMMARY.md
  - section-index
  - mkdocstrings:
      handlers:
        python:
          import:
            - https://docs.python-requests.org/en/master/objects.inv
            - https://omegaconf.readthedocs.io/en/latest/objects.inv
            - https://lightning.ai/docs/pytorch/stable/objects.inv
            - https://docs.pytest.org/en/stable/objects.inv
            - https://flax.readthedocs.io/en/latest/objects.inv
            - https://docs.python.org/3/objects.inv
            - https://pytorch.org/docs/stable/objects.inv
            - https://jax.readthedocs.io/en/latest/objects.inv
            - https://mit-ll-responsible-ai.github.io/hydra-zen/objects.inv
          options:
            docstring_style: google
            members_order: source
            annotations_path: brief
            show_docstring_attributes: true
            modernize_annotations: true
            show_source: false
            show_submodules: false
            separate_signature: true
            signature_crossrefs: true
            show_signature_annotations: true
            allow_inspection: true
  - mkdocs-video:
      is_video: True
      video_muted: True
      video_controls: True
      css_style:
        width: "100%"

  # - pymdownx.details
# todo: take a look at https://github.com/drivendataorg/cookiecutter-data-science/blob/master/docs/mkdocs.yml
#   - admonition
#   - tables
#   - toc:
#       toc_depth: 2