# mkdocs.yml
# Top-level config for mkdocs
# See: https://www.mkdocs.org/user-guide/configuration/
site_name: Rerun Python APIs
site_url: https://ref.rerun.io/docs/python/
repo_url: https://github.com/rerun-io/rerun/

# Files in `docs/` that are contributor-facing source materials and should
# not ship as part of the published site (mkdocs copies non-`.md` files
# verbatim by default).
exclude_docs: |
  writing_docs.md
  gen_common_index.py
  SUMMARY.txt
  templates/

# Use the material theme
# Override some options for nav: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/
theme:
  name: "material"
  features:
    - navigation.indexes
    - navigation.instant
    - navigation.tracking
    - search.share

plugins:
  - search: # https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/
      # Copy-pasted from https://squidfunk.github.io/mkdocs-material/plugins/search/#config.separator
      # with the addition of underscore. Splits things for better partial matching.
      # Further exploration of the parts at the link.
      separator: '[\s\-,:!=\[\]()"/_]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
  - autorefs
  - mkdocstrings: # https://mkdocstrings.github.io/usage/#global-options
      custom_templates: docs/templates # Override the function template.
      enable_inventory: true # Let others cross reference our docs.
      handlers:
        python:
          paths: ["rerun_sdk", "."] # Lookup python modules relative to this path
          inventories: # Cross-references for python and numpy
            - https://arrow.apache.org/docs/objects.inv
            - https://docs.python.org/3.10/objects.inv
            - https://numpy.org/doc/stable/objects.inv
            - https://ipython.readthedocs.io/en/stable/objects.inv
            - https://datafusion.apache.org/python/objects.inv
          options: # https://mkdocstrings.github.io/python/usage/#globallocal-options
            docstring_section_style: spacy # list spacy table
            docstring_style: numpy
            heading_level: 3
            filters: [
                "!__attrs_clear__", # For internal use
                "!^_[^_]", # Hide things starting with a single underscore
                "!as_component_batches", # Inherited from AsComponents
                "!num_instances", # Inherited from AsComponents
                "!__doc__", # griffe merges extension and stubs :(
                "!__module__", # griffe merges extension and stubs :(
                "!__weakref__", # griffe merges extension and stubs :(
              ]
            inherited_members: true
            members_order: source # The order of class members
            merge_init_into_class: false # Not compatible with `inherited_members`
            separate_signature: true # Render signature via griffe (needed for signature_crossrefs)
            show_signature_annotations: true # Show type annotations (incl. return types) in the signature
            show_if_no_docstring: false # We intentionally hide archetype fields
            show_source: no
            extra:
              load_external_modules: true
            preload_modules:
              - rerun_bindings
            annotations_path: brief
            signature_crossrefs: true
            find_stubs_package: true
            extensions:
              - griffe_warnings_deprecated
              - griffe_public_redundant_aliases

  - gen-files: # https://oprypin.github.io/mkdocs-gen-files
      scripts:
        - docs/gen_common_index.py
  - literate-nav: # https://oprypin.github.io/mkdocs-literate-nav
      nav_file: SUMMARY.txt
  # Keep legacy `common/<page>` URLs working. We dropped the `common/` URL
  # prefix and collapsed the old function-category pages
  # (initialization_functions, logging_functions, etc.) into the flat
  # `rerun` page. These stubs preserve the old URLs for inbound links
  # (docs, examples, blog posts, external sites).
  - redirects: # https://github.com/mkdocs/mkdocs-redirects
      redirect_maps:
        common/index.md: index.md
        common/archetypes.md: archetypes.md
        common/components.md: components.md
        common/datatypes.md: datatypes.md
        common/catalog.md: catalog.md
        common/utilities.md: utilities.md
        common/server.md: server.md
        common/notebook.md: notebook.md
        common/authentication.md: auth.md
        common/urdf_support.md: urdf.md
        common/blueprint_apis.md: blueprint.md
        common/blueprint_archetypes.md: blueprint_archetypes.md
        common/blueprint_components.md: blueprint_components.md
        common/blueprint_datatypes.md: blueprint_datatypes.md
        common/blueprint_views.md: blueprint_views.md
        common/initialization_functions.md: rerun.md
        common/logging_functions.md: rerun.md
        common/property_functions.md: rerun.md
        common/columnar_api.md: rerun.md
        common/script_helpers.md: rerun.md
        common/other_classes_and_functions.md: rerun.md
        common/custom_data.md: rerun.md

# https://www.mkdocs.org/user-guide/configuration/#markdown_extensions
# https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/
markdown_extensions:
  - admonition # https://squidfunk.github.io/mkdocs-material/reference/admonitions/
  - pymdownx.highlight # https://mkdocstrings.github.io/usage/theming/#syntax-highlighting
  - pymdownx.superfences
  - toc:
      toc_depth: 4

# Some extra styling
extra_css:
  - css/mkdocstrings.css

# https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/
extra:
  version:
    provider: mike
    default: latest