conf.py

"""Sphinx configuration for the Python Wiki."""

from __future__ import annotations

import os
from datetime import datetime
from pathlib import Path

import sys

sys.path.insert(0, str(Path(__file__).parent / "oauth"))
# Autodoc imports oauth/app.py which reads these at module level
os.environ.setdefault("GITHUB_CLIENT_ID", "docs-placeholder")
os.environ.setdefault("GITHUB_CLIENT_SECRET", "docs-placeholder")

# Litestar's @get() decorator replaces functions with handler objects.
# Patch the module so autodoc can find the actual functions.
import app as _app  # noqa: E402

for _name in ("health", "auth", "callback"):
    _handler = getattr(_app, _name)
    if hasattr(_handler, "fn"):
        _fn = _handler.fn
        _fn.__module__ = "app"
        setattr(_app, _name, _fn)

project = "Python Wiki"
copyright = f"{datetime.now().year}, Python Software Foundation"
author = "Python Community"

extensions = [
    "myst_parser",
    "sphinx.ext.autodoc",
    "sphinx.ext.viewcode",
    "sphinx_copybutton",
    "sphinx_design",
]

templates_path = ["_templates"]
exclude_patterns = [
    "_build", "_raw", "_exclude", "_redirects_html", "scripts", ".github", ".claude",
    "Thumbs.db", ".DS_Store", "venv", ".venv",
    "node_modules", "uv.lock", "pyproject.toml", "Makefile",
    "**/_attachments", "_extra", "oauth",
]

# Allow building a single wiki section or subsection:
#   WIKI=psf                       - build only the PSF wiki
#   WIKI=psf SECTION=Packaging     - build only psf/Packaging
#   WIKI=python SECTION=Advocacy   - build only python/Advocacy
_wiki_only = os.environ.get("WIKI")
if _wiki_only:
    _all_wikis = {"python", "psf", "jython"}
    for _w in _all_wikis - {_wiki_only}:
        exclude_patterns.append(f"{_w}/**")

    _section = os.environ.get("SECTION")
    if _section:
        # Exclude all sibling subdirectories and top-level pages in the wiki,
        # keeping only: the target section, the wiki's index.md, and root index.md
        from pathlib import Path

        _wiki_path = Path(_wiki_only)
        if _wiki_path.is_dir():
            # Exclude sibling subdirectories
            for _d in _wiki_path.iterdir():
                if _d.is_dir() and _d.name != _section and _d.name != "_attachments":
                    exclude_patterns.append(f"{_wiki_only}/{_d.name}/**")
            # Exclude top-level .md files except the wiki's own index
            for _f in _wiki_path.glob("*.md"):
                if _f.name != "index.md":
                    exclude_patterns.append(f"{_wiki_only}/{_f.name}")

source_suffix = {
    ".rst": "restructuredtext",
    ".md": "markdown",
}

master_doc = "index"
language = "en"

# -- MyST configuration ------------------------------------------------------
myst_enable_extensions = [
    "colon_fence",
    "deflist",
    "fieldlist",
    "html_admonition",
    "html_image",
    # "linkify",  # disabled: very slow on 3500+ files of converted wiki content
    # "replacements",  # disabled: converts .. to ellipsis inside link URLs, breaking 4786 relative links
    # "smartquotes",  # disabled: unnecessary for wiki content, marginal perf cost
    "strikethrough",
    "tasklist",
]
myst_heading_anchors = 0

# Suppress warnings from converted MoinMoin content
suppress_warnings = [
    "myst.header",
    "myst.xref_missing",
    "myst.directive_unknown",
    "myst.substitution",
    "toc.not_readable",
    "toc.excluded",
    "misc.highlighting_failure",
    "image.not_readable",
    "toc.not_included",
    "ref.doc",
    "docutils",
]

# -- Copy button settings ----------------------------------------------------
copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
copybutton_prompt_is_regexp = True
copybutton_remove_prompts = True

# -- HTML output -------------------------------------------------------------
html_theme = "shibuya"
html_title = "Python Wiki"
html_static_path = ["_static"]
html_css_files = ["custom.css"]
html_show_sourcelink = False
html_extra_path = ["_redirects_html", "_extra"]

html_context = {
    "source_type": "github",
    "source_user": "psf",
    "source_repo": "wiki",
    "source_docs_path": "/",
}

html_theme_options = {
    "accent_color": "blue",
    "github_url": "https://github.com/psf/wiki",
    "twitter_url": "https://x.com/ThePSF",
    "mastodon_url": "https://fosstodon.org/@ThePSF",
    "linkedin_url": "https://www.linkedin.com/company/thepsf",
    "nav_links": [
        {"title": "Python Wiki", "url": "python/index"},
        {"title": "PSF Wiki", "url": "psf/index"},
        {"title": "Jython Wiki", "url": "jython/index"},
        {
            "title": "Contribute",
            "children": [
                {
                    "title": "Edit with CMS",
                    "url": "edit/index.html",
                    "resource": True,
                    "summary": "Use the web-based editor to create or edit wiki pages",
                },
                {
                    "title": "Edit on GitHub",
                    "url": "https://github.com/psf/wiki",
                    "summary": "Fork the repository and submit changes via pull request",
                },
            ],
        },
    ],
}


# -- Attachments -------------------------------------------------------------
# MoinMoin wiki pages reference attachments as relative ``attachments/X/file``
# paths.  The actual files live in ``{wiki}/_attachments/X/`` which is excluded
# from the Sphinx source tree.  Two things happen at build-finished:
#
# 1. Referenced attachment files are copied into the build output so that
#    ``<img src="attachments/...">`` tags (from ``![](attachments/...)``) work.
#
# 2. MyST turns ``[text](attachments/...)`` links into broken anchor refs
#    (``href="#attachments/..."``).  We rewrite those to proper relative URLs
#    so the files can actually be downloaded.

import re as _re
import shutil as _shutil
from urllib.parse import unquote as _unquote

_ATTACH_RE = _re.compile(r'attachments/((?:[^()\"\s]|\(\w+\))+)')
_HREF_ANCHOR_RE = _re.compile(r'href="#(\.?/?attachments/)')


def _copy_wiki_attachments(app, exception):
    if exception:
        return

    srcdir = Path(app.srcdir)
    outdir = Path(app.outdir)

    for wiki in ("psf", "python", "jython"):
        attach_src = srcdir / wiki / "_attachments"
        if not attach_src.exists():
            continue

        # --- pass 1: copy referenced attachment files into build output ---
        for md_file in (srcdir / wiki).rglob("*.md"):
            if "_attachments" in md_file.parts or "_exclude" in md_file.parts:
                continue

            content = md_file.read_text(errors="ignore")
            refs = _ATTACH_RE.findall(content)
            if not refs:
                continue

            html_dir = outdir / md_file.relative_to(srcdir).parent

            for ref in refs:
                for candidate in (_unquote(ref), ref):
                    src_file = attach_src / candidate
                    if src_file.exists() and src_file.is_file():
                        dst = html_dir / "attachments" / ref
                        dst.parent.mkdir(parents=True, exist_ok=True)
                        if not dst.exists():
                            _shutil.copy2(src_file, dst)
                        break

    # --- pass 2: fix href="#attachments/..." → href="attachments/..." ---
    for html_file in outdir.rglob("*.html"):
        html = html_file.read_text(errors="ignore")
        if "#attachments/" not in html:
            continue
        fixed = _HREF_ANCHOR_RE.sub(r'href="attachments/', html)
        if fixed != html:
            html_file.write_text(fixed, encoding="utf-8")


def setup(app):
    app.connect("build-finished", _copy_wiki_attachments)


# -- Redirects ---------------------------------------------------------------
# Static redirect HTML files live in _redirects_html/ and are copied into the
# build output via html_extra_path. To regenerate:
#   python scripts/gen_redirect_pages.py
# To update the source mapping:
#   python scripts/gen_old_wiki_redirects.py