docs/conf.py

# Configuration file for the Sphinx documentation builder.

import os
import re

from docutils import nodes

# -- Project information
project = "rules_python"
copyright = "2023, The Bazel Authors"
author = "Bazel"

# NOTE: These are overriden by -D flags via --@sphinxdocs//sphinxdocs:extra_defines
version = "0.0.0"
release = version

# -- General configuration
# See https://www.sphinx-doc.org/en/master/usage/configuration.html
# for more settings

# Any extensions here not built into Sphinx must also be added to
# the dependencies of //docs:sphinx-builder
extensions = [
    "autodoc2",
    "sphinx.ext.autosectionlabel",
    "sphinx.ext.doctest",
    "sphinx.ext.duration",
    "sphinx.ext.extlinks",
    "sphinx.ext.intersphinx",
    "myst_parser",
    "sphinx_rtd_theme",  # Necessary to get jquery to make flyout work
    "sphinx_bzl.bzl",
    "sphinx_reredirects",
]

autodoc2_packages = [
    "sphinx_bzl",
    "runfiles",
]

autodoc2_output_dir = "api/py"
autodoc2_sort_names = True
autodoc2_class_docstring = "both"
autodoc2_index_template = """
Python APIs
====================

This page contains auto-generated API reference documentation [#f1]_.

.. toctree::
   :titlesonly:

{% for package in top_level %}
   {{ package }}
{%- endfor %}

.. [#f1] Created with `sphinx-autodoc2 <https://github.com/chrisjsewell/sphinx-autodoc2>`_

"""


autodoc2_docstring_parser_regexes = [
    (".*", "myst"),
]

# NOTE: The redirects generation will clobber existing files.
redirects = {
    "api/tools/precompiler/index": "/api/rules_python/tools/precompiler/index.html",
    "api/python/py_library": "/api/rules_python/python/py_library.html",
    "api/python/py_binary": "/api/rules_python/python/py_binary.html",
    "api/python/py_test": "/api/rules_python/python/py_test.html",
    "api/python/defs": "/api/rules_python/python/defs.html",
    "api/python/index": "/api/rules_python/python/index.html",
    "api/python/py_runtime_info": "/api/rules_python/python/py_runtime_info.html",
    "api/python/private/common/py_library_rule_bazel": "/api/rules_python/python/private/py_library_rule.html",
    "api/python/private/common/py_test_rule_bazel": "/api/rules_python/python/private/py_test_rule_bazel.html",
    "api/python/private/common/py_binary_rule_bazel": "/api/rules_python/python/private/py_binary_rule.html",
    "api/python/private/common/py_runtime_rule": "/api/rules_python/python/private/py_runtime_rule.html",
    "api/python/extensions/pip": "/api/rules_python/python/extensions/pip.html",
    "api/python/extensions/python": "/api/rules_python/python/extensions/python.html",
    "api/python/entry_points/py_console_script_binary": "/api/rules_python/python/entry_points/py_console_script_binary.html",
    "api/python/cc/py_cc_toolchain_info": "/api/rules_python/python/cc/py_cc_toolchain_info.html",
    "api/python/cc/index": "/api/rules_python/python/cc/index.html",
    "api/python/py_cc_link_params_info": "/api/rules_python/python/py_cc_link_params_info.html",
    "api/python/runtime_env_toolchains/index": "/api/rules_python/python/runtime_env_toolchains/index.html",
    "api/python/pip": "/api/rules_python/python/pip.html",
    "api/python/config_settings/index": "/api/rules_python/python/config_settings/index.html",
    "api/python/packaging": "/api/rules_python/python/packaging.html",
    "api/python/py_runtime": "/api/rules_python/python/py_runtime.html",
    "api/sphinxdocs/sphinx": "/api/sphinxdocs/sphinxdocs/sphinx.html",
    "api/sphinxdocs/sphinx_stardoc": "/api/sphinxdocs/sphinxdocs/sphinx_stardoc.html",
    "api/sphinxdocs/readthedocs": "/api/sphinxdocs/sphinxdocs/readthedocs.html",
    "api/sphinxdocs/index": "sphinxdocs/index.html",
    "api/sphinxdocs/private/sphinx_docs_library": "/api/sphinxdocs/sphinxdocs/private/sphinx_docs_library.html",
    "api/sphinxdocs/sphinx_docs_library": "/api/sphinxdocs/sphinxdocs/sphinx_docs_library.html",
    "api/sphinxdocs/inventories/index": "/api/sphinxdocs/sphinxdocs/inventories/index.html",
    "pip.html": "pypi/index.html",
    "pypi-dependencies.html": "pypi/index.html",
}

exclude_patterns = ["_includes/*"]
templates_path = ["_templates"]
primary_domain = None  # The default is 'py', which we don't make much use of
nitpicky = True

# Ignore nitpicks for missing cross-references to external objects.
# These are typically objects that aren't documented or aren't easily linked
# via intersphinx mapping, so we suppress warnings for them to keep the build clean.
nitpick_ignore_regex = [
    ("py:class", r"docutils\..*"),
    ("py:obj", r"sphinx\.util\.docutils\..*"),
    ("py:obj", r"sphinx\.util\.docfields\..*"),
    ("py:class", r"sphinx\.util\.typing\..*"),
    ("py:class", r"sphinx_bzl\.bzl\..*"),
    ("py:class", r"typing_extensions\.TypeAlias"),
    ("bzl:obj", r":current_py_cc_headers_abi3"),
    ("bzl:obj", r":python"),
    ("bzl:type", r"T"),
    ("bzl:type", r"input_value"),
    ("bzl:type", r"DepsetBuilder"),
    ("bzl:type", r"RunfilesBuilder"),
    ("bzl:type", r"BuiltinPyInfo"),
    ("bzl:type", r".*SentinelInfo"),
    ("bzl:type", r".*SphinxDocsLibraryInfo"),
    ("bzl:type", r".*_SphinxRunInfo"),
]

# --- Intersphinx configuration

intersphinx_mapping = {
    "python": ("https://docs.python.org/3", None),
    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
    "bazel": ("https://bazel.build/", "bazel_inventory.inv"),
}

# --- Extlinks configuration
extlinks = {
    "gh-issue": (
        "https://github.com/bazel-contrib/rules_python/issues/%s",
        "#%s issue",
    ),
    "gh-path": ("https://github.com/bazel-contrib/rules_python/tree/main/%s", "%s"),
    "gh-pr": ("https://github.com/bazel-contrib/rules_python/pull/%s", "#%s PR"),
}

# --- MyST configuration
# See https://myst-parser.readthedocs.io/en/latest/configuration.html
# for more settings

# See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
# for additional extensions.
myst_enable_extensions = [
    "fieldlist",
    "attrs_block",
    "attrs_inline",
    "colon_fence",
    "deflist",
    "substitution",
]

myst_substitutions = {}

# --- sphinx_stardoc configuration

bzl_default_repository_name = "@rules_python"

# -- Options for HTML output
# See https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
# For additional html settings

# See https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html for
# them-specific options
html_theme = "sphinx_rtd_theme"
html_theme_options = {}

# The html_context settings are part of the jinja context used by the themes.
html_context = {
    # This controls whether the flyout menu is shown. It is always false
    # because:
    # * For local builds, the flyout menu is empty and doesn't show in the
    #   same place as for RTD builds. No point in showing it locally.
    # * For RTD builds, the flyout menu is always automatically injected,
    #   so having it be True makes the flyout show up twice.
    "READTHEDOCS": False,
    "PRODUCTION_DOMAIN": "readthedocs.org",
    # This is the path to a page's source (after the github user/repo/commit)
    "conf_py_path": "/docs/",
    "github_user": "bazelbuild",
    "github_repo": "rules_python",
    # The git version that was checked out, e.g. the tag or branch name
    "github_version": os.environ.get("READTHEDOCS_GIT_IDENTIFIER", ""),
    # For local builds, the github link won't work. Disabling it replaces
    # it with a "view source" link to view the source Sphinx saw, which
    # is useful for local development.
    "display_github": os.environ.get("READTHEDOCS") == "True",
    "commit": os.environ.get("READTHEDOCS_GIT_COMMIT_HASH", "unknown commit"),
    # Used by readthedocs_ext.external_version_warning extension
    # This is the PR number being built
    "current_version": os.environ.get("READTHEDOCS_VERSION", ""),
}

# Keep this in sync with the stardoc templates
html_permalinks_icon = "¶"

# These folders are copied to the documentation's HTML output
html_static_path = ["_static"]

# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
    "css/custom.css",
]

# -- Options for EPUB output
epub_show_urls = "footnote"

suppress_warnings = [
    # The autosectionlabel extension turns header titles into referencable
    # names. Unfortunately, CHANGELOG.md has many duplicate header titles,
    # which creates lots of warning spam. Just ignore them.
    "autosectionlabel.*"
]


def _pep_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
    match = re.search(r"\d+", text)
    pep_num = match.group(0) if match else text
    pep_url = f"https://peps.python.org/pep-{pep_num.zfill(4)}/"
    display_text = text if text.startswith("PEP") else f"PEP {pep_num}"
    node = nodes.reference(rawtext, display_text, refuri=pep_url, **options)
    return [node], []


def setup(app):
    # Pygments says it supports starlark, but it doesn't seem to actually
    # recognize `starlark` as a name. So just manually map it to python.
    from sphinx.highlighting import lexer_classes

    app.add_lexer("starlark", lexer_classes["python"])
    app.add_role("pep", _pep_role)