Infra: Rename and refactor canonical ref directive to inject reST links

CAM-Gerlach · Aug 3, 2022 · Jul 8, 2022 · Jul 8, 2022 · Jul 22, 2022 · Jul 23, 2022
commit 3f50ab6068c1f1e3cc1a911b98f18823642f5ac6
@@ -10,7 +10,7 @@
 
 from pep_sphinx_extensions.pep_processor.html import pep_html_builder
 from pep_sphinx_extensions.pep_processor.html import pep_html_translator
-from pep_sphinx_extensions.pep_processor.parsing import pep_canonical_content_directive
+from pep_sphinx_extensions.pep_processor.parsing import pep_banner_directive
 from pep_sphinx_extensions.pep_processor.parsing import pep_parser
 from pep_sphinx_extensions.pep_processor.parsing import pep_role
 from pep_sphinx_extensions.pep_processor.transforms import pep_references
@@ -96,9 +96,11 @@ def setup(app: Sphinx) -> dict[str, bool]:
 
     # Register custom directives
     app.add_directive(
-        'canonical-content', pep_canonical_content_directive.CanonicalContent)
+        "pep-banner", pep_banner_directive.PEPBanner)
     app.add_directive(
-        'canonical-content-pypa', pep_canonical_content_directive.CanonicalContentPyPA)
+        "canonical-doc", pep_banner_directive.CanonicalDocBanner)
+    app.add_directive(
+        "canonical-pypa-spec", pep_banner_directive.CanonicalPyPASpecBanner)
 
     # Register event callbacks
     app.connect("builder-inited", _update_config_for_builder)  # Update configuration values for builder used

@@ -6,48 +6,32 @@
 from docutils.parsers import rst
 
 
-class CanonicalContent(rst.Directive):
-    """Insert an admonition pointing readers to a PEP's canonical content."""
+PYPA_SPEC_BASE_URL = "https://packaging.python.org/en/latest/specifications/"
+
+
+class PEPBanner(rst.Directive):
+    """Insert a special banner admonition in a PEP document."""
 
     has_content = True
     required_arguments = 0
-    optional_arguments = 2
+    optional_arguments = 1
     final_argument_whitespace = True
     option_spec = {}
 
-    default_canonical_link_title = "the Python docs"
-    default_canonical_link_uri = "https://docs.python.org/"
-    generic_canonical_link_title = "this link"
-    use_default_link = True
+    admonition_pre_template = ""
+    admonition_pre_text = ""
+    admonition_post_text = ""
 
-    admonition_pre_template = (
-        "This PEP is a historical document; the up-to-date, canonical "
-        "documentation can now be found at `{link_title} <{link_uri}>`__."
-    )
-    admonition_pre_text = (
-        "This PEP is a historical document; the up-to-date, canonical "
-        "documentation can now be found elsewhere."
-    )
-    admonition_post_text = (
-        "See :pep:`1` for how to propose changes."
-    )
+    admonition_class = nodes.important
+    css_classes = ["pep-banner"]
 
 
     def run(self) -> list[nodes.admonition]:
 
-        if self.arguments or (self.use_default_link and not self.content):
-            if self.arguments:
-                link_title = self.generic_canonical_link_title
-                link_uri = self.arguments[0]
-                if len(self.arguments) >= 2:
-                    link_title = self.arguments[1]
-            else:
-                link_title = self.default_canonical_link_title
-                link_uri = self.default_canonical_link_uri
-
+        if self.arguments:
+            link_content = self.arguments[0]
             pre_text = self.admonition_pre_template.format(
-                link_uri=link_uri, link_title=link_title)
-
+                link_content=link_content)
         else:
             pre_text = self.admonition_pre_text
 
@@ -63,8 +47,8 @@ def run(self) -> list[nodes.admonition]:
         post_text_node.extend(post_node + post_msg)
 
         source_lines = [pre_text] + list(self.content or []) + [post_text]
-        admonition_node = nodes.important(
-            "\n".join(source_lines), classes=["canonical-content"])
+        admonition_node = self.admonition_class(
+            "\n".join(source_lines), classes=self.css_classes)
 
         admonition_node.append(pre_text_node)
         if self.content:
@@ -75,26 +59,43 @@ def run(self) -> list[nodes.admonition]:
         return [admonition_node]
 
 
-class CanonicalContentPyPA(CanonicalContent):
-    """Insert a specialized admonition for PyPA packaging specifications."""
-
-    generic_canonical_link_title = "packaging"
-    use_default_link = False
+class CanonicalDocBanner(PEPBanner):
+    """Insert an admonition pointing readers to a PEP's canonical docs."""
 
     admonition_pre_template = (
         "This PEP is a historical document; the up-to-date, canonical "
-        "`{link_title} specification "
-        "<https://packaging.python.org/en/latest/specifications/{link_uri}/>`__ "
+        "documentation can now be found at {link_content}."
+    )
+    admonition_pre_text = (
+        "This PEP is a historical document; the up-to-date, canonical "
+        "documentation can now be found elsewhere."
+    )
+    admonition_post_text = (
+        "See :pep:`1` for how to propose changes."
+    )
+
+    css_classes = [*PEPBanner.css_classes, "canonical-doc"]
+
+
+
+class CanonicalPyPASpecBanner(PEPBanner):
+    """Insert a specialized admonition for PyPA packaging specifications."""
+
+    admonition_pre_template = (
+        "This PEP is a historical document; the up-to-date, canonical spec, "
+        "{link_content}, "
         "is maintained on the `PyPA specs page "
-        "<https://packaging.python.org/en/latest/specifications/index.html>`__."
+        f"<{PYPA_SPEC_BASE_URL}>`__."
     )
     admonition_pre_text = (
         "This PEP is a historical document; the up-to-date, canonical "
         "specification is maintained on the `PyPA specs page "
-        "<https://packaging.python.org/en/latest/specifications/index.html>`__."
+        f"<{PYPA_SPEC_BASE_URL}>`__."
     )
     admonition_post_text = (
         "See the `PyPA specification update process "
         "<https://www.pypa.io/en/latest/specifications/#handling-fixes-and-other-minor-updates>`__ "
         "for how to propose changes."
     )
+
+    css_classes = [*PEPBanner.css_classes, "canonical-pypa-spec"]