From f82973df463fa97ceacd8f95e8ee337d15c5aa6e Mon Sep 17 00:00:00 2001 From: CAM Gerlach Date: Sat, 18 Dec 2021 17:23:14 -0600 Subject: [PATCH] Don't auto-add inline links to ref section & rm if empty, per #2130 (#2155) Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> --- pep2html.py | 31 +++++++++- .../pep_processor/transforms/pep_footer.py | 56 +++---------------- 2 files changed, 36 insertions(+), 51 deletions(-) diff --git a/pep2html.py b/pep2html.py index 9a2b666f0d7..24b7c16fe2f 100755 --- a/pep2html.py +++ b/pep2html.py @@ -45,6 +45,7 @@ import random import time from io import open +from pathlib import Path try: from html import escape except ImportError: @@ -52,7 +53,7 @@ from docutils import core, nodes, utils from docutils.readers import standalone -from docutils.transforms import peps, frontmatter, Transform +from docutils.transforms import frontmatter, peps, Transform from docutils.parsers import rst class DataError(Exception): @@ -433,6 +434,32 @@ def apply(self): elif name == 'version' and len(body): utils.clean_rcs_keywords(para, self.rcs_keyword_substitutions) + +class PEPFooter(Transform): + """Remove the References section if it is empty when rendered.""" + + # Uses same priority as docutils.transforms.TargetNotes + default_priority = 520 + + def apply(self): + pep_source_path = Path(self.document['source']) + if not pep_source_path.match('pep-*'): + return # not a PEP file, exit early + + # Iterate through sections from the end of the document + for section in reversed(self.document): + if not isinstance(section, nodes.section): + continue + title_words = section[0].astext().lower().split() + if 'references' in title_words: + # Remove references section if there are no displayed + # footnotes (it only has title & link target nodes) + if all(isinstance(ref_node, (nodes.title, nodes.target)) + for ref_node in section): + section.parent.remove(section) + break + + class PEPReader(standalone.Reader): supported = ('pep',) @@ -453,7 +480,7 @@ def get_transforms(self): transforms.remove(frontmatter.DocTitle) transforms.remove(frontmatter.SectionSubTitle) transforms.remove(frontmatter.DocInfo) - transforms.extend([PEPHeaders, peps.Contents, peps.TargetNotes]) + transforms.extend([PEPHeaders, peps.Contents, PEPFooter]) return transforms settings_default_overrides = {'pep_references': 1, 'rfc_references': 1} diff --git a/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py b/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py index 5fa1b3844d4..39dad0404b2 100644 --- a/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py +++ b/pep_sphinx_extensions/pep_processor/transforms/pep_footer.py @@ -4,8 +4,6 @@ from docutils import nodes from docutils import transforms -from docutils.transforms import misc -from docutils.transforms import references from pep_sphinx_extensions import config @@ -13,14 +11,9 @@ class PEPFooter(transforms.Transform): """Footer transforms for PEPs. - - Appends external links to footnotes. + - Removes the References section if it is empty when rendered. - Creates a link to the (GitHub) source text. - TargetNotes: - Locate the `References` section, insert a placeholder at the end - for an external target footnote insertion transform, and schedule - the transform to run immediately. - Source Link: Create the link to the source file from the document source path, and append the text to the end of the document. @@ -35,43 +28,18 @@ def apply(self) -> None: if not pep_source_path.match("pep-*"): return # not a PEP file, exit early - doc = self.document[0] - reference_section = copyright_section = None - # Iterate through sections from the end of the document - num_sections = len(doc) - for i, section in enumerate(reversed(doc)): + for section in reversed(self.document[0]): if not isinstance(section, nodes.section): continue title_words = section[0].astext().lower().split() if "references" in title_words: - reference_section = section + # Remove references section if there are no displayed + # footnotes (it only has title & link target nodes) + if all(isinstance(ref_node, (nodes.title, nodes.target)) + for ref_node in section): + section.parent.remove(section) break - elif "copyright" in title_words: - copyright_section = num_sections - i - 1 - - # Add a references section if we didn't find one - if not reference_section: - reference_section = nodes.section() - reference_section += nodes.title("", "References") - self.document.set_id(reference_section) - if copyright_section: - # Put the new "References" section before "Copyright": - doc.insert(copyright_section, reference_section) - else: - # Put the new "References" section at end of doc: - doc.append(reference_section) - - # Add and schedule execution of the TargetNotes transform - pending = nodes.pending(references.TargetNotes) - reference_section.append(pending) - self.document.note_pending(pending, priority=0) - - # If there are no references after TargetNotes has finished, remove the - # references section - pending = nodes.pending(misc.CallBack, details={"callback": _cleanup_callback}) - reference_section.append(pending) - self.document.note_pending(pending, priority=1) # Add link to source text and last modified date if pep_source_path.stem != "pep-0000": @@ -79,16 +47,6 @@ def apply(self) -> None: self.document += _add_commit_history_info(pep_source_path) -def _cleanup_callback(pending: nodes.pending) -> None: - """Remove an empty "References" section. - - Called after the `references.TargetNotes` transform is complete. - - """ - if len(pending.parent) == 2: # and <pending> - pending.parent.parent.remove(pending.parent) - - def _add_source_link(pep_source_path: Path) -> nodes.paragraph: """Add link to source text on VCS (GitHub)""" source_link = config.pep_vcs_url + pep_source_path.name