From 32abe0210092e6e074d9c2cc1862a3cf7c2421c5 Mon Sep 17 00:00:00 2001 From: Ilya Priven Date: Wed, 14 Jun 2023 07:11:23 -0400 Subject: [PATCH] docs: ref redirector (#15432) Makes the HTML builder generate a _refs.html file that redirects (global) refs (when provided as a hash i.e. `_refs.html#some-ref`) to the appropriate document. This allows tools (e.g. #15431) to link to well-known refs. --- docs/source/conf.py | 2 +- docs/source/html_builder.py | 50 +++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 docs/source/html_builder.py diff --git a/docs/source/conf.py b/docs/source/conf.py index 80097ef5b3a8..683b2a6785b3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -35,7 +35,7 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ["sphinx.ext.intersphinx"] +extensions = ["sphinx.ext.intersphinx", "docs.source.html_builder"] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/docs/source/html_builder.py b/docs/source/html_builder.py new file mode 100644 index 000000000000..49d58dda12ec --- /dev/null +++ b/docs/source/html_builder.py @@ -0,0 +1,50 @@ +from __future__ import annotations + +import json +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 + + +class MypyHTMLBuilder(StandaloneHTMLBuilder): + def __init__(self, app: Sphinx) -> None: + super().__init__(app) + self._ref_to_doc = {} + + 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 _write_ref_redirector(self) -> None: + p = Path(self.outdir) / "_refs.html" + data = f""" + + + + + + """ + p.write_text(textwrap.dedent(data)) + + def finish(self) -> None: + super().finish() + self._write_ref_redirector() + + +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}