2021-06-08 20:37:55 -04:00
|
|
|
"""Sphinx extensions for performant PEP processing"""
|
|
|
|
|
|
|
|
from __future__ import annotations
|
|
|
|
|
|
|
|
from typing import TYPE_CHECKING
|
|
|
|
|
2022-01-09 13:07:03 -05:00
|
|
|
from docutils import nodes
|
|
|
|
from docutils.parsers.rst import states
|
2021-06-08 20:37:55 -04:00
|
|
|
from docutils.writers.html5_polyglot import HTMLTranslator
|
2022-01-09 13:07:03 -05:00
|
|
|
from sphinx import environment
|
2021-06-08 20:37:55 -04:00
|
|
|
|
2022-01-09 13:07:03 -05:00
|
|
|
from pep_sphinx_extensions.pep_processor.html import pep_html_builder
|
2021-06-08 20:37:55 -04:00
|
|
|
from pep_sphinx_extensions.pep_processor.html import pep_html_translator
|
|
|
|
from pep_sphinx_extensions.pep_processor.parsing import pep_parser
|
|
|
|
from pep_sphinx_extensions.pep_processor.parsing import pep_role
|
2021-06-12 13:51:14 -04:00
|
|
|
from pep_sphinx_extensions.pep_zero_generator.pep_index_generator import create_pep_zero
|
2021-06-08 20:37:55 -04:00
|
|
|
|
|
|
|
if TYPE_CHECKING:
|
|
|
|
from sphinx.application import Sphinx
|
|
|
|
|
|
|
|
# Monkeypatch sphinx.environment.default_settings as Sphinx doesn't allow custom settings or Readers
|
2022-01-21 06:03:51 -05:00
|
|
|
# This disables reading configuration from docutils.conf so as not to affect pep2html.py
|
|
|
|
environment.default_settings["_disable_config"] = True
|
2021-06-30 15:19:44 -04:00
|
|
|
|
2021-06-08 20:37:55 -04:00
|
|
|
|
|
|
|
def _depart_maths():
|
|
|
|
pass # No-op callable for the type checker
|
|
|
|
|
|
|
|
|
2021-06-30 15:19:44 -04:00
|
|
|
def _update_config_for_builder(app: Sphinx):
|
|
|
|
if app.builder.name == "dirhtml":
|
2022-01-16 17:33:05 -05:00
|
|
|
app.env.settings["pep_url"] = "../pep-{:0>4}"
|
2021-06-30 15:19:44 -04:00
|
|
|
|
|
|
|
|
2021-06-08 20:37:55 -04:00
|
|
|
def setup(app: Sphinx) -> dict[str, bool]:
|
|
|
|
"""Initialize Sphinx extension."""
|
|
|
|
|
2022-01-09 13:07:03 -05:00
|
|
|
environment.default_settings["pep_url"] = "pep-{:0>4}.html"
|
2022-01-28 18:24:08 -05:00
|
|
|
environment.default_settings["halt_level"] = 2 # Fail on Docutils warning
|
2022-01-09 13:07:03 -05:00
|
|
|
|
2021-06-08 20:37:55 -04:00
|
|
|
# Register plugin logic
|
2022-01-09 13:07:03 -05:00
|
|
|
app.add_builder(pep_html_builder.FileBuilder, override=True)
|
|
|
|
app.add_builder(pep_html_builder.DirectoryBuilder, override=True)
|
2022-01-16 17:33:05 -05:00
|
|
|
|
2021-06-08 20:37:55 -04:00
|
|
|
app.add_source_parser(pep_parser.PEPParser) # Add PEP transforms
|
2022-01-16 17:33:05 -05:00
|
|
|
|
2021-06-30 15:19:44 -04:00
|
|
|
app.set_translator("html", pep_html_translator.PEPTranslator) # Docutils Node Visitor overrides (html builder)
|
|
|
|
app.set_translator("dirhtml", pep_html_translator.PEPTranslator) # Docutils Node Visitor overrides (dirhtml builder)
|
2022-01-16 17:33:05 -05:00
|
|
|
|
|
|
|
app.add_role("pep", pep_role.PEPRole(), override=True) # Transform PEP references to links
|
|
|
|
|
|
|
|
# Register event callbacks
|
2021-06-30 15:19:44 -04:00
|
|
|
app.connect("builder-inited", _update_config_for_builder) # Update configuration values for builder used
|
2022-01-16 17:33:05 -05:00
|
|
|
app.connect("env-before-read-docs", create_pep_zero) # PEP 0 hook
|
2021-06-08 20:37:55 -04:00
|
|
|
|
|
|
|
# Mathematics rendering
|
|
|
|
inline_maths = HTMLTranslator.visit_math, _depart_maths
|
|
|
|
block_maths = HTMLTranslator.visit_math_block, _depart_maths
|
|
|
|
app.add_html_math_renderer("maths_to_html", inline_maths, block_maths) # Render maths to HTML
|
|
|
|
|
|
|
|
# Parallel safety: https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata
|
|
|
|
return {"parallel_read_safe": True, "parallel_write_safe": True}
|