From e92c4d6afa06143b6b69f8ebad1d0ea736b9663f Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <hugovk@users.noreply.github.com>
Date: Fri, 3 Feb 2023 21:34:17 +0200
Subject: [PATCH] PEP 1 and 12: Document Topic header (#2995)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
---
 Makefile                                              |  5 +++++
 infra/main.tf                                         | 11 +++++++++++
 pep-0001.txt                                          |  5 +++++
 pep-0012.rst                                          |  4 ++++
 pep-0012/pep-NNNN.rst                                 |  1 +
 .../pep_zero_generator/subindices.py                  |  2 ++
 6 files changed, 28 insertions(+)

diff --git a/Makefile b/Makefile
index c97937106..e247299be 100644
--- a/Makefile
+++ b/Makefile
@@ -11,6 +11,11 @@ RENDER_COMMAND=$(VENVDIR)/bin/python3 build.py -j $(JOBS) -o $(OUTPUT_DIR)
 html: venv
 	$(RENDER_COMMAND)
 
+## htmlview       to open the index page built by the html target in your browser
+.PHONY: htmlview
+htmlview: html
+	$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('build/index.html'))"
+
 ## dirhtml        to render PEPs to "index.html" files within "pep-NNNN" directories
 .PHONY: dirhtml
 dirhtml: venv rss
diff --git a/infra/main.tf b/infra/main.tf
index faf53b404..a2169a81e 100644
--- a/infra/main.tf
+++ b/infra/main.tf
@@ -39,6 +39,17 @@ resource "fastly_service_vcl" "peps" {
     EOT
   }
 
+  snippet {
+    name    = "topics"
+    type    = "recv"
+    content = <<-EOT
+        if (req.url ~ "^/topics($|/)") {
+          set req.http.Location = regsub(req.http.Location, "^/topics/?", "/topic/");
+          error 618;
+        }
+    EOT
+  }
+
   snippet {
     name    = "redirect"
     type    = "error"
diff --git a/pep-0001.txt b/pep-0001.txt
index 421aefb19..5560a7d74 100644
--- a/pep-0001.txt
+++ b/pep-0001.txt
@@ -605,6 +605,7 @@ optional and are described below.  All other headers are required.
     Status: <Draft | Active | Accepted | Provisional | Deferred | Rejected |
              Withdrawn | Final | Superseded>
     Type: <Standards Track | Informational | Process>
+  * Topic: <Governance | Packaging | Release | Typing>
   * Content-Type: text/x-rst
   * Requires: <pep numbers>
     Created: <date created on, in dd-mmm-yyyy format>
@@ -659,6 +660,10 @@ archives, rather than just a mailto: or hyperlink to the list itself.
 The Type header specifies the type of PEP: Standards Track,
 Informational, or Process.
 
+The optional Topic header lists the special topic, if any,
+the PEP belongs under.
+See the :ref:`topic-index` for the existing topics.
+
 The format of a PEP is specified with a Content-Type header.
 All PEPs must use reStructuredText (see :pep:`12`),
 and have a value of ``text/x-rst``, the default.
diff --git a/pep-0012.rst b/pep-0012.rst
index 3c488e10c..bea8a8083 100644
--- a/pep-0012.rst
+++ b/pep-0012.rst
@@ -121,6 +121,9 @@ directions below.
 
       Python-Version: 2.2
 
+- Add a Topic header if the PEP belongs under one shown at the :ref:`topic-index`.
+  Most PEPs don't.
+
 - Leave Post-History alone for now; you'll add dates and corresponding links
   to this header each time you post your PEP to the designated discussion forum
   (and update the Discussions-To header with said link, as above).
@@ -174,6 +177,7 @@ your PEP):
   Discussions-To: [URL]
   Status: Draft
   Type: [Standards Track | Informational | Process]
+  Topic: *[Governance | Packaging | Release | Typing]
   Content-Type: text/x-rst
   Requires: *[NNN]
   Created: [DD-MMM-YYYY]
diff --git a/pep-0012/pep-NNNN.rst b/pep-0012/pep-NNNN.rst
index cc66a0572..011616f6f 100644
--- a/pep-0012/pep-NNNN.rst
+++ b/pep-0012/pep-NNNN.rst
@@ -6,6 +6,7 @@ PEP-Delegate: <PEP delegate's real name>
 Discussions-To: <REQUIRED: URL of current canonical discussion thread>
 Status: <REQUIRED: Draft | Active | Accepted | Provisional | Deferred | Rejected | Withdrawn | Final | Superseded>
 Type: <REQUIRED: Standards Track | Informational | Process>
+Topic: <Governance | Packaging | Release | Typing>
 Content-Type: text/x-rst
 Requires: <pep numbers>
 Created: <date created on, in dd-mmm-yyyy format>
diff --git a/pep_sphinx_extensions/pep_zero_generator/subindices.py b/pep_sphinx_extensions/pep_zero_generator/subindices.py
index 293abe024..455a49dd8 100644
--- a/pep_sphinx_extensions/pep_zero_generator/subindices.py
+++ b/pep_sphinx_extensions/pep_zero_generator/subindices.py
@@ -57,6 +57,8 @@ the PEP index.
 
 def generate_topic_contents(docnames: list[str], env: BuildEnvironment):
     update_sphinx("topic/index", """\
+.. _topic-index:
+
 Topic Index
 ***********