Infra: Add tooltips to type/status in PEP 0 (#2838)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>

pep_sphinx_extensions/pep_processor/html/pep_html_translator.py

@@ -74,7 +74,7 @@ class PEPTranslator(html5.HTML5Translator):
         back_refs = node.parent["backrefs"]
         if self.settings.footnote_backlinks and len(back_refs) == 1:
             self.body.append(f'<a href="#{back_refs[0]}">')
-            self.context.append(f"</a>]")
+            self.context.append("</a>]")
         else:
             self.context.append("]")
 

pep_sphinx_extensions/pep_theme/static/style.css

@@ -248,6 +248,7 @@ table td {
     text-align: left;
     padding: 0.25rem 0.5rem 0.2rem;
 }
+table.pep-zero-table tr td:nth-child(1),
 table.pep-zero-table tr td:nth-child(2) {
     white-space: nowrap;
 }

pep_sphinx_extensions/pep_zero_generator/parser.py

@@ -126,16 +126,23 @@ class PEP:
     def __eq__(self, other):
         return self.number == other.number
 
+    @property
+    def shorthand(self) -> str:
+        """Return reStructuredText tooltip for the PEP type and status."""
+        type_code = self.pep_type[0].upper()
+        if self.status in HIDE_STATUS:
+            return f":abbr:`{type_code} ({self.pep_type})`"
+        status_code = self.status[0].upper()
+        return f":abbr:`{type_code}{status_code} ({self.pep_type}, {self.status})`"
+
     @property
     def details(self) -> dict[str, str | int]:
         """Return the line entry for the PEP."""
         return {
-            # how the type is to be represented in the index
-            "type": self.pep_type[0].upper(),
             "number": self.number,
             "title": self.title,
-            # how the status should be represented in the index
-            "status": " " if self.status in HIDE_STATUS else self.status[0].upper(),
+            # a tooltip representing the type and status
+            "shorthand": self.shorthand,
             # the author list as a comma-separated with only last names
             "authors": ", ".join(author.nick for author in self.authors),
         }

pep_sphinx_extensions/pep_zero_generator/subindices.py

@@ -56,7 +56,7 @@ the PEP index.
 
 
 def generate_topic_contents(docnames: list[str], env: BuildEnvironment):
-    update_sphinx(f"topic/index", """\
+    update_sphinx("topic/index", """\
 Topic Index
 ***********
 

pep_sphinx_extensions/pep_zero_generator/writer.py

@@ -74,8 +74,10 @@ class PEPZeroWriter:
         author_table_separator = "=" * max_name_len + "  " + "=" * len("email address")
         self.output.append(author_table_separator)
 
-    def emit_pep_row(self, *, type: str, status: str, number: int, title: str, authors: str) -> None:
-        self.emit_text(f"   * - {type}{status}")
+    def emit_pep_row(
+        self, *, shorthand: str, number: int, title: str, authors: str
+    ) -> None:
+        self.emit_text(f"   * - {shorthand}")
         self.emit_text(f"     - :pep:`{number} <{number}>`")
         self.emit_text(f"     - :pep:`{title.replace('`', '')} <{number}>`")
         self.emit_text(f"     - {authors}")
@@ -161,8 +163,9 @@ class PEPZeroWriter:
             self.emit_title("Reserved PEP Numbers")
             self.emit_column_headers()
             for number, claimants in sorted(self.RESERVED.items()):
-                self.emit_pep_row(type="", status="", number=number, title="RESERVED", authors=claimants)
-
+                self.emit_pep_row(
+                    shorthand="", number=number, title="RESERVED", authors=claimants
+                )
 
             self.emit_newline()
 

pep_sphinx_extensions/tests/pep_zero_generator/test_parser.py

@@ -4,6 +4,20 @@ import pytest
 
 from pep_sphinx_extensions.pep_zero_generator import parser
 from pep_sphinx_extensions.pep_zero_generator.author import Author
+from pep_sphinx_extensions.pep_zero_generator.constants import (
+    STATUS_ACCEPTED,
+    STATUS_ACTIVE,
+    STATUS_DEFERRED,
+    STATUS_DRAFT,
+    STATUS_FINAL,
+    STATUS_PROVISIONAL,
+    STATUS_REJECTED,
+    STATUS_SUPERSEDED,
+    STATUS_WITHDRAWN,
+    TYPE_INFO,
+    TYPE_PROCESS,
+    TYPE_STANDARDS,
+)
 from pep_sphinx_extensions.pep_zero_generator.errors import PEPError
 from pep_sphinx_extensions.tests.utils import AUTHORS_OVERRIDES
 
@@ -34,9 +48,8 @@ def test_pep_details(monkeypatch):
     assert pep8.details == {
         "authors": "GvR, Warsaw, Coghlan",
         "number": 8,
-        "status": " ",
+        "shorthand": ":abbr:`P (Process)`",
         "title": "Style Guide for Python Code",
-        "type": "P",
     }
 
 
@@ -79,3 +92,29 @@ def test_parse_authors_invalid():
 
     with pytest.raises(PEPError, match="no authors found"):
         parser._parse_authors(pep, "", AUTHORS_OVERRIDES)
+
+
+@pytest.mark.parametrize(
+    "test_type, test_status, expected",
+    [
+        (TYPE_INFO, STATUS_DRAFT, ":abbr:`I (Informational)`"),
+        (TYPE_INFO, STATUS_ACTIVE, ":abbr:`I (Informational)`"),
+        (TYPE_INFO, STATUS_ACCEPTED, ":abbr:`IA (Informational, Accepted)`"),
+        (TYPE_INFO, STATUS_DEFERRED, ":abbr:`ID (Informational, Deferred)`"),
+        (TYPE_PROCESS, STATUS_ACCEPTED, ":abbr:`PA (Process, Accepted)`"),
+        (TYPE_PROCESS, STATUS_ACTIVE, ":abbr:`P (Process)`"),
+        (TYPE_PROCESS, STATUS_FINAL, ":abbr:`PF (Process, Final)`"),
+        (TYPE_PROCESS, STATUS_SUPERSEDED, ":abbr:`PS (Process, Superseded)`"),
+        (TYPE_PROCESS, STATUS_WITHDRAWN, ":abbr:`PW (Process, Withdrawn)`"),
+        (TYPE_STANDARDS, STATUS_ACCEPTED, ":abbr:`SA (Standards Track, Accepted)`"),
+        (TYPE_STANDARDS, STATUS_REJECTED, ":abbr:`SR (Standards Track, Rejected)`"),
+        (TYPE_STANDARDS, STATUS_PROVISIONAL, ":abbr:`SP (Standards Track, Provisional)`"),  # fmt: skip
+    ],
+)
+def test_abbreviate_type_status(test_type, test_status, expected):
+    # set up dummy PEP object and monkeypatch attributes
+    pep = parser.PEP(Path("pep-0008.txt"))
+    pep.pep_type = test_type
+    pep.status = test_status
+
+    assert pep.shorthand == expected