# --------------------( LICENSE                            )--------------------
# Copyright (c) 2014-2025 Beartype authors.
# See "LICENSE" for further details.
#
# --------------------( SYNOPSIS                           )--------------------
# Project-wide MkDocs configuration, applied to all invocations of the MkDocs
# documentation generator within this project -- including both by directly
# running the external "mkdocs" command locally and by indirectly running that
# command remotely from GitHub Actions-based documentation workflows.
#
# --------------------( COMMANDS                           )--------------------
# Commonly used MkDocs commands include:
#     # Add a default MkDocs documentation tree to the current project:
#     cd ~/py/${PROJECT_NAME}
#     mkdocs new .
#
#     # Locally test the current MkDocs documentation tree:
#     mkdocs serve
#
#     # Remotely push to the GitHub Pages-hosted Project Site:
#     mkdocs gh-deploy

# ....................{ TODO                                }...................
#FIXME: Define all remaining relevant configuration options specified here:
#    https://www.mkdocs.org/user-guide/configuration

#FIXME: Pretty sure we need to include "black" in the "doc-ghp" extra. Why?
#Because "mkdocstrings-python" appears to optionally require that in common edge
#cases we will definitely hit. See also:
#    https://mkdocstrings.github.io/python/usage/configuration/signatures/#line_length

#FIXME: Enable some combination of "mkdocs-autoapi" and/or "mkdocs-api-autonav"
#to auto-generate an API reference. Maybe? @beartype is kinda non-trivial, but
#it would also be unfortunate if we had to do this manually. Research us up!

# ....................{ CORE                                }...................
# Human-readable name of the static site generated by MkDocs.
site_name: Beartype

# Human-readable description of this site, injected as a proper HTML-compliant
# "<meta...>" tag into the HTML header of each site page.
site_description: >-
  Unbearably fast near-real-time hybrid runtime-static type-checking in pure
  Python.

# Human-readable name(s) of the author(s) of this site.
site_author: "Beartype"

# Human-readable copyright line, typically injected into each page by the
# third-party theme configured below.
copyright: "Copyright (c) 2014-2025 Beartype authors."

# URL of the repository documented by this site. 
repo_url: https://github.com/beartype/beartype

# ....................{ PATHS                               }...................
# Relative or absolute dirname of the top-level MkDocs-specific input
# subdirectory documenting this repository with MkDocs-specific markdown.
docs_dir: 'docs'

# Relative or absolute dirname of the top-level MkDocs-specific output
# subdirectory storing all web-compliant files (e.g., HTML, CSS, JavaScript)
# generated by the "mkdocs build" subcommand required to render this site.
#
# Note that this dirname intentionally corresponds to the Jekyll-specific
# output dirname leveraged by our ".github/workflows/python_docs.yml" workflow.
site_dir: '_site'

# ....................{ MARKDOWN                            }...................
# List of all JavaScript-specific files required by this site. See also:
#    https://www.mkdocs.org/user-guide/configuration/#markdown_extensions
markdown_extensions:
  # MathJax Markdown extension, enabling MathJax-rendered math to be embedded in
  # Markdown with standard math syntax (e.g., LaTeX).
  #
  # Note that a competing KaTeX Markdown extension also exists, but that this
  # MathJax Markdown extension is widely considered to be superior.
  #
  # See also:
  #   https://squidfunk.github.io/mkdocs-material/reference/math
  - pymdownx.arithmatex:
     generic: true


# List of all JavaScript-specific files required by this site. See also:
#     https://www.mkdocs.org/user-guide/configuration/#extra_javascript
extra_javascript:
  # MathJax-specific JavaScript files. See also "pymdownx.arithmatex" above.
  - docs/js/mathjax.js
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

# ....................{ PLUGINS                             }...................
# List of all first- and third-party MkDocs plugins required by this site.
plugins:
  # ....................{ PLUGINS ~ builtin                 }...................
  # First-party MkDocs plugins bundled with Mkdocs itself.

  # Enable the builtin search bar, which the Material theme seamlessly
  # integrates with. See also:
  #     https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search
  - search

  # ....................{ PLUGINS ~ third-party             }...................
  # Third-party MkDocs plugins external to Mkdocs itself.

  #FIXME: Uncomment if and when we leverage MIKE to version documentation for
  #@beartype. Note that:
  #* "deploy_prefix: public" appears to be required by GitHub Pages. *shrug*
  #* We'll probably also need to add this at the root YAML level somewhere:
  #    extra:
  #      version:
  #        provider: mike
  #- mike:
  #    canonical_version: latest
  #    deploy_prefix: public

  # Automatically generate API reference documentation from Python docstrings
  # embedded inside the Python package defined by this project. See also:
  #     https://github.com/mkdocstrings/mkdocstrings
  - mkdocstrings:
      handlers:
        python:
          # ....................{ CORE                      }...................
          # List of all dirnames relative to this configuration file under which
          # to discover documentation.
          paths:
            # The current working directory.
            - "."

          # ....................{ OPTIONS                   }...................
          options:
            # Prefer NumpyDoc-style Python docstrings. By default,
            # "mkdocstrings" assumes Google-style Python docstrings.
            docstring_style: numpy

            # Style used to render docstrings sections. Choices include:
            # * "table": a simple table, usually with type, name and description
            #   columns.
            # * "list": a simple list, akin to what you get with the ReadTheDocs
            #   Sphinx theme.
            # * "spacy": a poor implementation of the amazing tables in Spacy's
            #   documentation. See also: https://spacy.io/api/doc
            #
            # Defaults to "table". Unsurprisingly, everyone prefers "spacy".
            docstring_section_style: spacy

            #!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            # CAUTION: Synchronize this list with the corresponing "doc-ghp:"
            # extra in our top-level "pyproject.toml" configuration.
            #!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
            # List of one or more third-party "mkdocstrings-python" extensions
            # to be enabled.
            extensions:
              # Expand the default "mkdocstrings-python" support for absolute
              # cross-references with additional support for relative
              # cross-references.
              #
              # Note that "mkdocstrings-python" technically already provides
              # out-of-the-box support for relative cross-references -- but
              # *ONLY* for paid subscribers. We get it. Really, we do. Like,
              # *REALLY* really. We're dead-broke, too. But a well-maintained
              # free-as-in-beer open-source alternative already exists! It's
              # hard to compete with free. Which is why @beartype doesn't go
              # there. Paid-only functionality only incentivizes competition.
              #
              # See also:
              # * Upstream documentation:
              #     https://analog-garage.github.io/mkdocstrings-python-xref
              # * Comparable paid "mkdocstrings-python" functionality:
              #     https://mkdocstrings.github.io/python/usage/configuration/docstrings/#relative_crossrefs
              - mkdocstrings-python-xref

            # ....................{ OPTIONS ~ heading       }...................
            # See also:
            #   https://mkdocstrings.github.io/python/usage/configuration/headings

            # Show one heading for each grouped category (i.e., kind of similar
            # attribute) defined by a submodule.
            show_category_heading: true

            # Show classnames as headings. By default, classnames are hidden.
            # That makes no sense, MkDocs. Nobody wants that! *sigh*
            show_root_heading: true

            # Prefix headings by Sphinx-style domain names disambiguating the
            # kinds of those headings:
            # * "attr" for attributes.
            # * "class" for classes.
            # * "func" for functions.
            # * "meth" for methods.
            # * "mod" for modules.
            show_symbol_type_heading: true

            # Prefix headings by the same names in the Table of Contents (ToC).
            show_symbol_type_toc: true

            # ....................{ OPTIONS ~ members       }...................
            # See also:
            #   https://mkdocstrings.github.io/python/usage/configuration/members

            # Show attributes inherited into subclasses by their superclasses.
            inherited_members: true

            # ....................{ OPTIONS ~ signature     }...................
            # See also:
            #   https://mkdocstrings.github.io/python/usage/configuration/signatures

            # Show callable signatures of all @typing.overload-decorated
            # callables in code blocks below headers.
            show_overloads: true

            # Hide the implementation signature of overloaded callables, defined
            # as the signature associated with the overloaded callable
            # containing a non-empty body and *NOT* decorated by the
            # PEP 484-compliant @typing.overload decorator.
            overloads_only: true

            # Show callable signatures in code blocks below headers. By default,
            # callable signatures are embedded in headers. Since signatures
            # commonly contain type hints and parameters, this unwise default
            # commonly results in overly verbose and unreadable headers.
            separate_signature: true

            # Show both type hints and parameters in signatures. Naturally, both
            # are disabled by default. *sigh*
            show_signature_annotations: true
            show_signature_type_parameters: true

            #FIXME: This might be accessible only to paid subscribers. No idea!
            # Show cross-references to type hints in signatures.
            signature_crossrefs: true

          # ....................{ CROSS-REFERENCE           }...................
          # List of all inventories (i.e., external URLs to Sphinx-formatted
          # inventory files listing all Python attributes provided by the APIs
          # hosted at those URLs). Third-party attributes provided by an
          # inventory listed below will be implicitly linked to; all other
          # third-party attributes will remain unlinked.
          inventories:
            # Official inventory providing:
            # * All Python builtins.
            # * The standard Python library.
            - https://docs.python.org/3/objects.inv

            # Third-party inventory providing the NumPy API.
            - https://numpy.org/doc/stable/objects.inv

# ....................{ THEME                               }...................
# Third-party MkDocs UI theme currently employed by this project.
theme:
  # Material of Mkdocs. The one. The only. See also:
  #     https://squidfunk.github.io/mkdocs-material
  name: material

  #FIXME: Uncomment this after we actually define a favicon. Shouldn't be
  #terribly arduous. We just need to do it. Also, this should ideally be
  #specified as a remote URL if it's anything over 50k or so. I'd rather not
  #bloat the repo any more than we must. *sigh*
  # favicon: images/favicon.ico

  #FIXME: No idea. Should work, but let's at least comment this up. *sigh*
  icon:
    repo: fontawesome/brands/github

  # Theme-specific features.
  features:
    # Enable search highlighting, dynamically displaying all occurrences of the
    # search term in each found document.
    - search.highlight

    # Enable search suggestions, dynamically displaying the likeliest completion
    # for the last word which can be accepted with the <Right> arrow key.
    - search.suggest

    #FIXME: Seems useful, but let's research this a bit more, please.
    # - navigation.tabs
    # - navigation.instant

  # Theme-specific color scheme(s). See also:
  #     https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors
  palette:
    # Palette toggle for dark mode.
    #
    # Note that "slate" is Material's name for its default dark mode. *sigh*
    - scheme: slate
      toggle:
        icon: material/weather-night
        name: Switch to light mode

    # Palette toggle for light mode.
    #
    # Note that "default" is Material's name for its default light mode. I know.
    - scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode