Make the table of contents collapsed by default (#2364)

Author: AA-Turner

pep-0249.txt

@@ -12,8 +12,8 @@ Post-History:
 Replaces: 248
 
 
-`Introduction`_
-===============
+Introduction
+============
 
 This API has been defined to encourage similarity between the Python
 modules that are used to access databases.  By doing this, we hope to
@@ -35,11 +35,11 @@ encouraged to use this version of the specification as basis for new
 interfaces.
 
 
-`Module Interface`_
-===================
+Module Interface
+=================
 
-`Constructors`_
----------------
+Constructors
+------------
 
 Access to the database is made available through connection
 objects. The module must provide the following constructor for these:
@@ -53,8 +53,8 @@ objects. The module must provide the following constructor for these:
     which are database dependent. [1]_
 
 
-`Globals`_
-----------
+Globals
+-------
 
 These module globals must be defined:
 
@@ -107,8 +107,8 @@ These module globals must be defined:
     ============ ==============================================================
 
 
-`Exceptions`_
--------------
+Exceptions
+----------
 
 The module should make all error information available through these
 exceptions or subclasses thereof:
@@ -220,14 +220,14 @@ This is the exception inheritance layout::
 
 .. _Connection:
 
-`Connection Objects`_
-=====================
+Connection Objects
+==================
 
 Connection objects should respond to the following methods.
 
 
-`Connection methods`_
----------------------
+Connection methods
+------------------
 
 .. .close():
 .. _Connection.close:
@@ -283,8 +283,8 @@ Connection objects should respond to the following methods.
 
 .. _Cursor:
 
-`Cursor Objects`_
-=================
+Cursor Objects
+==============
 
 These objects represent a database cursor, which is used to manage the
 context of a fetch operation. Cursors created from the same connection
@@ -297,8 +297,8 @@ transaction support is implemented (see also the connection's
 Cursor Objects should respond to the following methods and attributes.
 
 
-`Cursor attributes`_
---------------------
+Cursor attributes
+-----------------
 
 .. _.description:
 
@@ -344,8 +344,8 @@ Cursor Objects should respond to the following methods and attributes.
         latter case to have the object return ``None`` instead of -1.
 
 
-`Cursor methods`_
------------------
+Cursor methods
+--------------
 
 .. _.callproc:
 .. _.callproc():
@@ -561,8 +561,8 @@ Cursor Objects should respond to the following methods and attributes.
 
 .. _Type Objects:
 
-`Type Objects and Constructors`_
-================================
+Type Objects and Constructors
+=============================
 
 Many databases need to have the input in a particular format for
 binding to an operation's input parameters.  For example, if an input
@@ -682,8 +682,8 @@ on input and output.
 
 .. _Implementation Hints:
 
-`Implementation Hints for Module Authors`_
-==========================================
+Implementation Hints for Module Authors
+=======================================
 
 * Date/time objects can be implemented as `Python datetime module
   <http://docs.python.org/library/datetime.html>`__ objects (available
@@ -769,8 +769,8 @@ on input and output.
   API to create the exception objects.
 
 
-`Optional DB API Extensions`_
-=============================
+Optional DB API Extensions
+==========================
 
 During the lifetime of DB API 2.0, module authors have often extended
 their implementations beyond what is required by this DB API
@@ -934,8 +934,8 @@ Cursor\ `.lastrowid`_
     *Warning Message:* "DB-API extension cursor.lastrowid used"
 
 
-`Optional Error Handling Extensions`_
-=====================================
+Optional Error Handling Extensions
+==================================
 
 The core DB API specification only introduces a set of exceptions
 which can be raised to report errors to the user. In some cases,
@@ -981,8 +981,8 @@ Cursors should inherit the ``.errorhandler`` setting from their
 connection objects at cursor creation time.
 
 
-`Optional Two-Phase Commit Extensions`_
-=======================================
+Optional Two-Phase Commit Extensions
+====================================
 
 Many databases have support for two-phase commit (TPC) which allows
 managing transactions across multiple database connections and other
@@ -994,8 +994,8 @@ API should be implemented. NotSupportedError_ should be raised, if the
 database backend support for two-phase commit can only be checked at
 run-time.
 
-`TPC Transaction IDs`_
-----------------------
+TPC Transaction IDs
+-------------------
 
 As many databases follow the XA specification, transaction IDs are
 formed from three components:
@@ -1034,8 +1034,8 @@ Transaction IDs are created with the `.xid()`_ Connection method:
     represent transaction IDs with tuples rather than a custom object.
 
 
-`TPC Connection Methods`_
--------------------------
+TPC Connection Methods
+----------------------
 
 .. _.tpc_*:
 .. _.tpc_*():
@@ -1117,8 +1117,8 @@ Transaction IDs are created with the `.xid()`_ Connection method:
 
 
 
-`Frequently Asked Questions`_
-=============================
+Frequently Asked Questions
+==========================
 
 The database SIG often sees reoccurring questions about the DB API
 specification. This section covers some of the issues people sometimes
@@ -1153,8 +1153,8 @@ between databases and makes writing portable code impossible.
 
 
 
-`Major Changes from Version 1.0 to Version 2.0`_
-================================================
+Major Changes from Version 1.0 to Version 2.0
+=============================================
 
 The Python Database API 2.0 introduces a few major changes compared to
 the 1.0 version. Because some of these changes will cause existing DB
@@ -1197,8 +1197,8 @@ Post-publishing additions to the DB API 2.0 specification:
   functionality were specified.
 
 
-`Open Issues`_
-==============
+Open Issues
+===========
 
 Although the version 2.0 specification clarifies a lot of questions
 that were left open in the 1.0 version, there are still some remaining
@@ -1213,8 +1213,8 @@ issues which should be addressed in future versions:
 
 
 
-`Footnotes`_
-============
+Footnotes
+=========
 
 .. [1] As a guideline the connection constructor parameters should be
     implemented as keyword parameters for more intuitive use and
@@ -1298,8 +1298,8 @@ issues which should be addressed in future versions:
     of the ``.rowcount`` attribute.
 
 
-`Acknowledgements`_
-===================
+Acknowledgements
+================
 
 Many thanks go to Andrew Kuchling who converted the Python Database
 API Specification 2.0 from the original HTML format into the PEP
@@ -1312,7 +1312,7 @@ Many thanks to Daniele Varrazzo for converting the specification from
 text PEP format to ReST PEP format, which allows linking to various
 parts.
 
-`Copyright`_
-============
+Copyright
+=========
 
 This document has been placed in the Public Domain.

pep-0512.txt

@@ -465,8 +465,8 @@ Work for this is being tracked at
 https://github.com/python/core-workflow/issues/7.
 
 
-Create https://git.python.org
-'''''''''''''''''''''''''''''
+Create ``https://git.python.org``
+'''''''''''''''''''''''''''''''''
 
 Just as hg.python.org [#h.p.o]_ currently points to the Mercurial
 repository for Python, git.python.org should do the equivalent for

pep_sphinx_extensions/pep_processor/html/pep_html_builder.py

@@ -38,6 +38,7 @@ def get_doc_context(self, docname: str, body: str, _metatags: str) -> dict:
         toc_tree = self.env.tocs[docname].deepcopy()
         if len(toc_tree[0]) > 1:
             toc_tree = toc_tree[0][1]  # don't include document title
+            del toc_tree[0]  # remove contents node
             for node in toc_tree.findall(nodes.reference):
                 node["refuri"] = node["anchorname"] or '#'  # fix targets
             toc = self.render_partial(toc_tree)["fragment"]

pep_sphinx_extensions/pep_processor/html/pep_html_translator.py

@@ -89,6 +89,17 @@ def depart_label(self, node) -> None:
         # Close the def tags
         self.body.append("</dt>\n<dd>")
 
+    def visit_bullet_list(self, node):
+        if isinstance(node.parent, nodes.section) and "contents" in node.parent["names"]:
+            self.body.append("<details><summary>Contents</summary>")
+            self.context.append("</details>")
+        super().visit_bullet_list(node)
+
+    def depart_bullet_list(self, node):
+        super().depart_bullet_list(node)
+        if isinstance(node.parent, nodes.section) and "contents" in node.parent["names"]:
+            self.body.append(self.context.pop())
+
     def unknown_visit(self, node: nodes.Node) -> None:
         """No processing for unknown node types."""
         pass

pep_sphinx_extensions/pep_processor/transforms/pep_contents.py

@@ -17,8 +17,7 @@ def apply(self) -> None:
         if not Path(self.document["source"]).match("pep-*"):
             return  # not a PEP file, exit early
         # Create the contents placeholder section
-        title = nodes.title("", "", nodes.Text("Contents"))
-        contents_section = nodes.section("", title)
+        contents_section = nodes.section("")
         if not self.document.has_name("contents"):
             contents_section["names"].append("contents")
         self.document.note_implicit_target(contents_section)

pep_sphinx_extensions/pep_theme/static/style.css

@@ -118,6 +118,11 @@ pre {
     padding: .5rem .75rem;
 }
 
+/* Contents rules */
+details > summary {
+    font-weight: bold;
+}
+
 /* Definition list rules */
 dl dt {
     font-weight: bold;