Infra: Move "Source" and "Last modified" from <article> to <footer> (#4977)

Author: hugovk

pep_sphinx_extensions/__init__.py

@@ -23,6 +23,7 @@
     pep_parser,
     pep_role,
 )
+from pep_sphinx_extensions.pep_processor.transforms import pep_footer
 from pep_sphinx_extensions.pep_processor.transforms import pep_references
 from pep_sphinx_extensions.pep_zero_generator.pep_index_generator import create_pep_zero
 
@@ -68,6 +69,9 @@ def set_description(
     else:
         context["description"] = "Python Enhancement Proposals (PEPs)"
 
+    if pagename != "pep-0000":
+        context.update(pep_footer.get_page_footer_context(pagename))
+
 
 def setup(app: Sphinx) -> dict[str, bool]:
     """Initialize Sphinx extension."""

pep_sphinx_extensions/pep_processor/transforms/pep_footer.py

@@ -10,12 +10,6 @@ class PEPFooter(transforms.Transform):
     """Footer transforms for PEPs.
 
      - Remove the References/Footnotes section if it is empty when rendered.
-     - Create a link to the (GitHub) source text.
-
-    Source Link:
-        Create the link to the source file from the document source path,
-        and append the text to the end of the document.
-
     """
 
     # Uses same priority as docutils.transforms.TargetNotes
@@ -44,31 +38,21 @@ def apply(self) -> None:
                     section.parent.extend(to_hoist)
                     section.parent.remove(section)
 
-        # Add link to source text and last modified date
-        if pep_source_path.stem != "pep-0000":
-            if pep_source_path.stem != "pep-0210":  # 210 is entirely empty, skip
-                self.document += nodes.transition()
-            self.document += _add_source_link(pep_source_path)
-            self.document += _add_commit_history_info(pep_source_path)
-
-
-def _add_source_link(pep_source_path: Path) -> nodes.paragraph:
-    """Add link to source text on VCS (GitHub)"""
-    source_link = f"https://github.com/python/peps/blob/main/peps/{pep_source_path.name}"
-    link_node = nodes.reference("", source_link, refuri=source_link)
-    return nodes.paragraph("", "Source: ", link_node)
-
-
-def _add_commit_history_info(pep_source_path: Path) -> nodes.paragraph:
-    """Use local git history to find last modified date."""
-    try:
-        iso_time = _LAST_MODIFIED_TIMES[pep_source_path.stem]
-    except KeyError:
-        return nodes.paragraph()
 
-    commit_link = f"https://github.com/python/peps/commits/main/peps/{pep_source_path.name}"
-    link_node = nodes.reference("", f"{iso_time} GMT", refuri=commit_link)
-    return nodes.paragraph("", "Last modified: ", link_node)
+def get_page_footer_context(pep_stem: str) -> dict[str, str]:
+    """Template context for the page footer, rendered by ``page.html``."""
+    context = {
+        "source_link": (
+            f"https://github.com/python/peps/blob/main/peps/{pep_stem}.rst"
+        ),
+    }
+    iso_time = _LAST_MODIFIED_TIMES.get(pep_stem, "")
+    if iso_time:
+        context["last_modified"] = iso_time
+        context["commit_link"] = (
+            f"https://github.com/python/peps/commits/main/peps/{pep_stem}.rst"
+        )
+    return context
 
 
 def _get_last_modified_timestamps():

pep_sphinx_extensions/pep_theme/static/mq.css

@@ -38,13 +38,17 @@
         padding: 0.5rem 1rem 0;
         width: 100%;
     }
-    section#pep-page-section > article {
+    section#pep-page-section > article,
+    section#pep-page-section > footer#pep-page-footer {
         max-width: 37em;
         width: 74%;
         float: right;
         margin-right: 0;
         font-size: 1rem;
     }
+    section#pep-page-section > footer#pep-page-footer {
+        clear: right;
+    }
     nav#pep-sidebar {
         width: 24%;
         float: left;
@@ -61,7 +65,8 @@
   }
 }
 @media (min-width: 60em) {
-    section#pep-page-section > article {
+    section#pep-page-section > article,
+    section#pep-page-section > footer#pep-page-footer {
         max-width: 56em;
         padding-left: 3.2%;
         padding-right: 3.2%;
@@ -158,7 +163,8 @@
         display: none;
     }
 
-    section#pep-page-section > article {
+    section#pep-page-section > article,
+    section#pep-page-section > footer#pep-page-footer {
         float: none;
         max-width: 100%;
         width: auto;

pep_sphinx_extensions/pep_theme/templates/page.html

@@ -72,6 +72,14 @@ <h2>Contents</h2>
             {%- endif %}
         </nav>
         {%- endif %}
+        {%- if source_link %}
+        <footer id="pep-page-footer">
+            <p>Source: <a href="{{ source_link }}">{{ source_link }}</a></p>
+            {%- if last_modified %}
+            <p>Last modified: <a href="{{ commit_link }}">{{ last_modified }} UTC</a></p>
+            {%- endif %}
+        </footer>
+        {%- endif %}
     </section>
     <script src="{{ pathto('_static/colour_scheme.js', resource=True) }}"></script>
     <script src="{{ pathto('_static/wrap_tables.js', resource=True) }}"></script>

pep_sphinx_extensions/tests/pep_processor/transform/test_pep_footer.py

@@ -2,30 +2,27 @@
 
 from pep_sphinx_extensions.pep_processor.transforms import pep_footer
 
-from ...conftest import PEP_ROOT
 
+def test_get_page_footer_context():
+    out = pep_footer.get_page_footer_context("pep-0008")
 
-def test_add_source_link():
-    out = pep_footer._add_source_link(PEP_ROOT / "pep-0008.rst")
-
-    assert "https://github.com/python/peps/blob/main/peps/pep-0008.rst" in str(out)
-
-
-def test_add_commit_history_info():
-    out = pep_footer._add_commit_history_info(PEP_ROOT / "pep-0008.rst")
-
-    assert str(out).startswith(
-        "<paragraph>Last modified: "
-        '<reference refuri="https://github.com/python/peps/commits/main/peps/pep-0008.rst">'
+    assert out["source_link"] == (
+        "https://github.com/python/peps/blob/main/peps/pep-0008.rst"
+    )
+    assert out["commit_link"] == (
+        "https://github.com/python/peps/commits/main/peps/pep-0008.rst"
     )
-    # A variable timestamp comes next, don't test that
-    assert str(out).endswith("</reference></paragraph>")
+    # A variable timestamp, don't test the exact value
+    assert out["last_modified"]
 
 
-def test_add_commit_history_info_invalid():
-    out = pep_footer._add_commit_history_info(PEP_ROOT / "pep-not-found.rst")
+def test_get_page_footer_context_no_history():
+    out = pep_footer.get_page_footer_context("pep-not-found")
 
-    assert str(out) == "<paragraph/>"
+    # No git history -> only the static source link
+    assert out == {
+        "source_link": "https://github.com/python/peps/blob/main/peps/pep-not-found.rst",
+    }
 
 
 def test_get_last_modified_timestamps():