conf.py

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

import os
import sys
from importlib.metadata import version as get_version

# Used when building API docs, put the dependencies
# of any class you are documenting here
autodoc_mock_imports = []

# Add the module path to sys.path here.
# If the directory is relative to the documentation root,
# use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath("../.."))

project = "poseinterface"
copyright = "2025, The poseinterface developers"
author = "The poseinterface developers"
try:
    full_version = get_version(project)
    # Splitting the release on '+' to remove the commit hash
    release = full_version.split('+', 1)[0]
except LookupError:
    # if git is not initialised, still allow local build
    # with a dummy version
    release = "0.0.0"

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    "sphinx.ext.napoleon",
    "sphinx.ext.autodoc",
    "sphinx.ext.githubpages",
    "sphinx_autodoc_typehints",
    "sphinx.ext.autosummary",
    "sphinx.ext.viewcode",
    "sphinx.ext.intersphinx",
    "sphinx_sitemap",
    "sphinx_gallery.gen_gallery",
    "myst_parser",
    "nbsphinx",
    "sphinx_design",
]

# Configure the myst parser to enable cool markdown features
# See https://sphinx-design.readthedocs.io
myst_enable_extensions = [
    "amsmath",
    "colon_fence",
    "deflist",
    "dollarmath",
    "fieldlist",
    "html_admonition",
    "html_image",
    "linkify",
    "replacements",
    "smartquotes",
    "strikethrough",
    "substitution",
    "tasklist",
]
# Automatically add anchors to markdown headings
myst_heading_anchors = 3

# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]

# Automatically generate stub pages for API
autosummary_generate = True
autodoc_default_flags = ["members", "inherited-members"]

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = [
    "**.ipynb_checkpoints",
    # to ensure that include files (partial pages) aren't built, exclude them
    # https://github.com/sphinx-doc/sphinx/issues/1965#issuecomment-124732907
    "**/includes/**",
    # Auto-generated by sphinx-gallery; contains dangling refs to ignored examples
    "sg_execution_times.rst",
]

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = "pydata_sphinx_theme"
html_title = "poseinterface"

# Remove the primary (left) sidebar for specific pages
html_sidebars = {
    "benchmark-dataset": [],
}

# Customize the theme
html_theme_options = {
    "icon_links": [
        {
            # Label for this link
            "name": "GitHub",
            # URL where the link will redirect
            "url": "https://github.com/neuroinformatics-unit/poseinterface",  # required
            # Icon class (if "type": "fontawesome"),
            # or path to local image (if "type": "local")
            "icon": "fa-brands fa-github",
            # The type of image to be used (see below for details)
            "type": "fontawesome",
        }
    ],
    "logo": {
        "text": f"{project} v{release}",
    },
}

# Redirect the webpage to another URL
# Sphinx will create the appropriate CNAME file in the build directory
# The default is the URL of the GitHub pages
# https://www.sphinx-doc.org/en/master/usage/extensions/githubpages.html
github_user = "neuroinformatics-unit"
html_baseurl = "https://poseinterface.neuroinformatics.dev"
sitemap_url_scheme = "{link}"

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']


intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
    "sleap_io": ("https://io.sleap.ai/latest/", None),
}

# -- Sphinx-Gallery configuration -------------------------------------------
sphinx_gallery_conf = {
    "examples_dirs": ["../../examples"],
    "gallery_dirs": ["auto_examples"],
    # Patterns of example filenames to ignore (not built or shown in gallery).
    # Use this for scripts that depend on data/resources not available in CI
    # or on the developer's machine (e.g. files on a specific mount point).
    # To re-enable an example, remove its pattern from this list.
    "ignore_pattern": r"SWC-plusmaze_to_benchmark",
}

# -- linkcheck configuration -------------------------------------------------
linkcheck_timeout = 60  # defaut is 30
linkcheck_retries = 3  # default is 1

# The linkcheck builder will skip verifying that anchors exist when checking
# these URLs (because they are generated dynamically)
linkcheck_anchors_ignore_for_url = [
    "https://cocodataset.org/",
]
# A list of regular expressions that match URIs that should not be checked
linkcheck_ignore = [
    r"https://docutils\.sourceforge\.io/.*",       # returns 403
    r"https://www\.contributor-covenant\.org/.*",  # flaky
]
# Add request headers for specific domains (e.g. to avoid rate-limiting)
linkcheck_request_headers = {
    "https://github.com": {
        "Authorization": f"Bearer {os.environ.get('GITHUB_TOKEN', '')}",
    },
}

# -- myst-parser configuration -------------------------------------------------

myst_url_schemes = {
    "http": None,
    "https": None,
    "ftp": None,
    "mailto": None,
    "github-docs": (
        "https://docs.github.com/en/"
        "{{path}}#{{fragment}}"
    ),
    "myst-parser": (
        "https://myst-parser.readthedocs.io/en/latest/"
        "{{path}}#{{fragment}}"
    ),
    "sphinx-doc": (
        "https://www.sphinx-doc.org/en/master/usage/"
        "{{path}}#{{fragment}}"
    ),
}