docs/source/html_builder.py

from __future__ import annotations

import json
import os
import textwrap
from pathlib import Path
from typing import Any

from sphinx.addnodes import document
from sphinx.application import Sphinx
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.environment import BuildEnvironment

from mypy.main import define_options


class MypyHTMLBuilder(StandaloneHTMLBuilder):
    strict_file: Path

    def __init__(self, app: Sphinx, env: BuildEnvironment) -> None:
        super().__init__(app, env)
        self._ref_to_doc = {}
        self.strict_file = Path(self.srcdir) / "strict_list.rst"
        self._add_strict_list()

    def write_doc(self, docname: str, doctree: document) -> None:
        super().write_doc(docname, doctree)
        self._ref_to_doc.update({_id: docname for _id in doctree.ids})

    def _add_strict_list(self) -> None:
        strict_flags: list[str]
        _, strict_flags, _ = define_options()
        strict_part = ", ".join(f":option:`{s} <mypy {s}>`" for s in strict_flags)
        if (
            not strict_part
            or strict_part.isspace()
            or len(strict_part) < 20
            or len(strict_part) > 2000
        ):
            raise ValueError(f"{strict_part=}, which doesn't look right (by a simple heuristic).")
        self.strict_file.write_text(
            "For this version of mypy, the list of flags enabled by strict is: " + strict_part
        )

    def _verify_error_codes(self) -> None:
        from mypy.errorcodes import error_codes

        missing_error_codes = {c for c in error_codes if f"code-{c}" not in self._ref_to_doc}
        if missing_error_codes:
            raise ValueError(
                f"Some error codes are not documented: {', '.join(sorted(missing_error_codes))}"
            )

    def _write_ref_redirector(self) -> None:
        if os.getenv("VERIFY_MYPY_ERROR_CODES"):
            self._verify_error_codes()
        p = Path(self.outdir) / "_refs.html"
        data = f"""
        <html>
        <body>
        <script>
        const ref_to_doc = {json.dumps(self._ref_to_doc)};
        const hash = window.location.hash.substring(1);
        const doc = ref_to_doc[hash];
        if (doc) {{
            window.location.href = doc + '.html' + '#' + hash;
        }} else {{
            window.document.innerText = 'Unknown reference: ' + hash;
        }}
        </script>
        </body>
        </html>
        """
        p.write_text(textwrap.dedent(data))

    def finish(self) -> None:
        super().finish()
        self._write_ref_redirector()
        self.strict_file.unlink()


def setup(app: Sphinx) -> dict[str, Any]:
    app.add_builder(MypyHTMLBuilder, override=True)

    return {"version": "0.1", "parallel_read_safe": True, "parallel_write_safe": True}