Infra: Use PEP abstract/introduction as HTML and OG description (#3801)

pep_sphinx_extensions/__init__.py

@@ -2,17 +2,27 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+import html
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
 
 from docutils.writers.html5_polyglot import HTMLTranslator
 from sphinx import environment
 
-from pep_sphinx_extensions.generate_rss import create_rss_feed
-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_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.generate_rss import (
+    create_rss_feed,
+    get_from_doctree,
+    pep_abstract,
+)
+from pep_sphinx_extensions.pep_processor.html import (
+    pep_html_builder,
+    pep_html_translator,
+)
+from pep_sphinx_extensions.pep_processor.parsing import (
+    pep_banner_directive,
+    pep_parser,
+    pep_role,
+)
 from pep_sphinx_extensions.pep_processor.transforms import pep_references
 from pep_sphinx_extensions.pep_zero_generator.pep_index_generator import create_pep_zero
 
@@ -43,6 +53,22 @@ def _post_build(app: Sphinx, exception: Exception | None) -> None:
     create_rss_feed(app.doctreedir, app.outdir)
 
 
+def set_description(
+    app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], doctree
+) -> None:
+    if not pagename.startswith("pep-"):
+        return
+
+    full_path = Path(app.doctreedir) / f"{pagename}.doctree"
+    abstract = get_from_doctree(full_path, "Abstract")
+    if abstract:
+        if len(abstract) > 256:
+            abstract = abstract[:253] + "..."
+        context["description"] = html.escape(abstract)
+    else:
+        context["description"] = "Python Enhancement Proposals (PEPs)"
+
+
 def setup(app: Sphinx) -> dict[str, bool]:
     """Initialize Sphinx extension."""
 
@@ -78,6 +104,7 @@ def setup(app: Sphinx) -> dict[str, bool]:
     # Register event callbacks
     app.connect("builder-inited", _update_config_for_builder)  # Update configuration values for builder used
     app.connect("env-before-read-docs", create_pep_zero)  # PEP 0 hook
+    app.connect('html-page-context', set_description)
 
     # Mathematics rendering
     inline_maths = HTMLTranslator.visit_math, None

pep_sphinx_extensions/generate_rss.py

@@ -50,14 +50,21 @@ def pep_creation(full_path: Path) -> dt.datetime:
 
 
 def pep_abstract(document: nodes.document) -> str:
-    """Return the first paragraph of the PEP abstract"""
+    """Return the first paragraph of the PEP abstract.
+    If not found, return the first paragraph of the introduction.
+    """
+    introduction = ""
     for node in document.findall(nodes.section):
         title_node = node.next_node(nodes.title)
         if title_node is None:
             continue
+
         if title_node.astext() == "Abstract":
             return node.next_node(nodes.paragraph).astext().strip().replace("\n", " ")
-    return ""
+        elif title_node.astext() == "Introduction":
+            introduction = node.next_node(nodes.paragraph).astext().strip().replace("\n", " ")
+
+    return introduction
 
 
 def _generate_items(doctree_dir: Path):

pep_sphinx_extensions/pep_theme/templates/page.html

@@ -14,14 +14,15 @@
     <link rel="stylesheet" href="{{ pathto('_static/pygments_dark.css', resource=True) }}" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark">
     <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss">
     <meta property="og:title" content='{{ title + " | peps.python.org"|safe }}'>
+    <meta property="og:description" content="{{ description }}">
     <meta property="og:type" content="website">
     <meta property="og:url" content="https://peps.python.org/{{ pagename }}/">
     <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)">
     <meta property="og:image" content="https://peps.python.org/_static/og-image.png">
     <meta property="og:image:alt" content="Python PEPs">
     <meta property="og:image:width" content="200">
     <meta property="og:image:height" content="200">
-    <meta name="description" content="Python Enhancement Proposals (PEPs)">
+    <meta name="description" content="{{ description }}">
     <meta name="theme-color" content="#3776ab">
 </head>
 <body>