From f1aac9deeeee64acdc759e58244081131b2d52f6 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Tue, 11 Jun 2024 00:23:44 -0600
Subject: [PATCH] Infra: Use PEP abstract/introduction as HTML and OG
description (#3801)
---
pep_sphinx_extensions/__init__.py | 41 +++++++++++++++----
pep_sphinx_extensions/generate_rss.py | 11 ++++-
.../pep_theme/templates/page.html | 3 +-
3 files changed, 45 insertions(+), 10 deletions(-)
diff --git a/pep_sphinx_extensions/__init__.py b/pep_sphinx_extensions/__init__.py
index 382d6bd4e5c..6a878eaf8ca 100644
--- a/pep_sphinx_extensions/__init__.py
+++ b/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
diff --git a/pep_sphinx_extensions/generate_rss.py b/pep_sphinx_extensions/generate_rss.py
index 5e5e0b8bc24..a20e71da033 100644
--- a/pep_sphinx_extensions/generate_rss.py
+++ b/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):
diff --git a/pep_sphinx_extensions/pep_theme/templates/page.html b/pep_sphinx_extensions/pep_theme/templates/page.html
index 8290a9f99ca..1bc41d89766 100644
--- a/pep_sphinx_extensions/pep_theme/templates/page.html
+++ b/pep_sphinx_extensions/pep_theme/templates/page.html
@@ -14,6 +14,7 @@
+
@@ -21,7 +22,7 @@
-
+