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

"""Sphinx configuration for the movement documentation."""

import os
import sys

import setuptools_scm

# 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 = "movement"
copyright = "2023, University College London"
author = "Niko Sirmpilatze"
try:
    release = setuptools_scm.get_version(root="../..", relative_to=__file__)
    release = release.split("+")[0]  # remove git hash
except LookupError:
    # if git is not initialised, still allow local build
    # with a dummy version
    release = "0.0.0"

is_dev = "dev" in release
doc_version = "dev" if is_dev else f"v{release}"
binder_branch = "main" if is_dev else f"v{release}"


# -- 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",
    "myst_parser",
    "nbsphinx",
    "notfound.extension",
    "sphinx_design",
    "sphinx_gallery.gen_gallery",
    "sphinx_sitemap",
    "sphinx.ext.autosectionlabel",
    "ablog",
]

# 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 = 4

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

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

# Prefix section labels with the document name
autosectionlabel_prefix_document = True

# 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/**",
    # exclude .py and .ipynb files in examples generated by sphinx-gallery
    # this is to prevent sphinx from complaining about duplicate source files
    "examples/*.ipynb",
    "examples/*.py",
    "examples/**/*.ipynb",
    "examples/**/*.py",
]

# Configure Sphinx gallery
sphinx_gallery_conf = {
    "examples_dirs": ["../../examples"],
    "filename_pattern": "/*.py",  # which files to execute before inclusion
    "gallery_dirs": ["examples"],  # output directory
    "run_stale_examples": True,  # re-run examples on each build
    # Integration with Binder, see https://sphinx-gallery.github.io/stable/configuration.html#generate-binder-links-for-gallery-notebooks-experimental
    "binder": {
        "org": "neuroinformatics-unit",
        "repo": "movement",
        "branch": binder_branch,  # Can be any branch, tag, or commit hash
        "binderhub_url": "https://mybinder.org",
        "dependencies": ["../../.binder/requirements.txt"],
    },
    "reference_url": {"movement": None},
    "default_thumb_file": "source/_static/data_icon.png",
    # default thumbnail image
    # Do not render config comments with the pattern
    # sphinx_gallery_config [= value]
    "remove_config_comments": True,
    # Mini-galleries config, see https://sphinx-gallery.github.io/stable/configuration.html#add-mini-galleries-for-api-documentation
    "backreferences_dir": "api/backreferences",
    # directory where function/class granular galleries are stored
}


# -- 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 = "movement"
html_logo = "_static/movement_favicon.svg"
html_favicon = "_static/movement_favicon.svg"
# 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/movement",
            # 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",
        },
        {
            "name": "Zulip (chat)",
            "url": "https://neuroinformatics.zulipchat.com/#narrow/stream/406001-Movement",
            "icon": "fa-solid fa-comments",
            "type": "fontawesome",
        },
    ],
    "switcher": {
        "json_url": "https://movement.neuroinformatics.dev/latest/_static/switcher.json",
        "version_match": doc_version,
    },
    "logo": {
        "text": f"{project} v{release}",
    },
    "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
    "footer_start": ["footer_start"],
    "footer_end": ["footer_end"],
    "external_links": [],
}

# 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://movement.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"]
html_css_files = [
    ("css/custom.css", {"priority": 100}),
]
html_js_files = [
    "js/contributors.js",  # javascript for contributors table
]
html_favicon = "_static/light-logo-niu.png"

# 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://gin.g-node.org/G-Node/Info/wiki/",
    "https://neuroinformatics.zulipchat.com/",
    "https://github.com/talmolab/sleap/blob/v1.3.3/sleap/info/write_tracking_h5.py",
]
# A list of regular expressions that match URIs that should not be checked
linkcheck_ignore = [
    "https://pubs.acs.org/doi/*",  # Checking dois is forbidden here
    "https://opensource.org/license/bsd-3-clause/",  # 403 error
    "https://www.sainsburywellcome.org/",  # ConnectTimeoutError
    "https://www.robots.ox.ac.uk/",  # 404 error
    "https://silvalab.codeberg.page/BraiAn/",  # SSLError despite working link
    "https://www.g-node.org/",  # frequent timeouts
    "https://www.contributor-covenant.org/*",  # frequent timeouts
    "https://docutils.sourceforge.io/*",  # 403 error
    "https://www.iso.org/",  # 403 error
    # Checking zenodo redirects (from concept doi to record) takes a long time
    "https://zenodo.org/doi/*",
    "https://zenodo.org/records/*",
    "https://doi.org/10.5281/zenodo.*",
    "https://abide.ics.ulisboa.pt/*"  # 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_url_schemes = {
    "http": None,
    "https": None,
    "ftp": None,
    "mailto": None,
    "movement-github": "https://github.com/neuroinformatics-unit/movement/{{path}}",
    "movement-zulip": "https://neuroinformatics.zulipchat.com/#narrow/stream/406001-Movement",
    "movement-community-calls": "https://neuroinformatics.zulipchat.com/#narrow/channel/406001-Movement/topic/Community.20Calls",
    "conda": "https://docs.conda.io/projects/conda/en/latest/{{path}}#{{fragment}}",
    "dlc": "https://www.mackenziemathislab.org/deeplabcut/",
    "gin": "https://gin.g-node.org/{{path}}#{{fragment}}",
    "github-docs": "https://docs.github.com/en/{{path}}#{{fragment}}",
    "myst-parser": "https://myst-parser.readthedocs.io/en/latest/{{path}}#{{fragment}}",
    "napari": "https://napari.org/stable/{{path}}",
    "setuptools-scm": "https://setuptools-scm.readthedocs.io/en/latest/{{path}}#{{fragment}}",
    "sleap": "https://sleap.ai/{{path}}#{{fragment}}",
    "sleap-docs": "https://docs.sleap.ai/latest/{{path}}#{{fragment}}",
    "sphinx-doc": "https://www.sphinx-doc.org/en/master/usage/{{path}}#{{fragment}}",
    "sphinx-gallery": "https://sphinx-gallery.github.io/stable/{{path}}#{{fragment}}",
    "xarray": "https://docs.xarray.dev/en/stable/{{path}}#{{fragment}}",
    "lp": "https://lightning-pose.readthedocs.io/en/stable/{{path}}#{{fragment}}",
    "via": "https://www.robots.ox.ac.uk/~vgg/software/via/{{path}}#{{fragment}}",
    "anipose": "https://anipose.readthedocs.io/en/latest/",
    "TRex": "https://trex.run/docs/",
    "uv": "https://docs.astral.sh/uv/{{path}}#{{fragment}}",
    "attrs": "https://www.attrs.org/en/stable/{{path}}#{{fragment}}",
    "pytest-benchmark": "https://pytest-benchmark.readthedocs.io/en/latest/{{path}}#{{fragment}}",
}

intersphinx_mapping = {
    "xarray": ("https://docs.xarray.dev/en/stable/", None),
    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
    "python": ("https://docs.python.org/3", None),
    "loguru": ("https://loguru.readthedocs.io/en/stable/", None),
    "pynwb": ("https://pynwb.readthedocs.io/en/stable/", None),
    "matplotlib": ("https://matplotlib.org/stable/", None),
    "numpy": ("https://numpy.org/doc/stable/", None),
    "attrs": ("https://www.attrs.org/en/stable/", None),
    "shapely": ("https://shapely.readthedocs.io/en/stable/", None),
}

# What to show on the 404 page
notfound_context = {
    "title": "Page Not Found",
    "body": """
<h1>Page Not Found</h1>

<p>Sorry, we couldn't find that page.</p>

<p>
We occasionally restructure the movement website,
and some links may have broken.
</p>

<p>Try using the search box or go to the homepage.</p>
""",
}

# Static files live in /<version>/_static/, but GH pages expects a single
# 404.html at root, so use latest version for all static asset URLs in 404 page
notfound_urls_prefix = "/latest/"