Make _prepend_prologue() and _append_epilogue() private (#13658)

Author: AA-Turner

sphinx/parsers.py

@@ -11,7 +11,7 @@
 from docutils.transforms.universal import SmartQuotes
 
 from sphinx.deprecation import _deprecation_warning
-from sphinx.util.rst import append_epilog, prepend_prolog
+from sphinx.util.rst import _append_epilogue, _prepend_prologue
 
 if TYPE_CHECKING:
     from docutils import nodes
@@ -100,9 +100,9 @@ def parse(self, inputstring: str | StringList, document: nodes.document) -> None
         self.finish_parse()
 
     def decorate(self, content: StringList) -> None:
-        """Preprocess reST content before parsing."""
-        prepend_prolog(content, self.config.rst_prolog)
-        append_epilog(content, self.config.rst_epilog)
+        """Preprocess reStructuredText content before parsing."""
+        _prepend_prologue(content, self._config.rst_prolog)
+        _append_epilogue(content, self._config.rst_epilog)
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:

sphinx/util/rst.py

@@ -1,11 +1,11 @@
-"""reST helper functions."""
+"""reStructuredText helper functions."""
 
 from __future__ import annotations
 
 import re
 from collections import defaultdict
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING
 from unicodedata import east_asian_width
 
 from docutils.parsers.rst import roles
@@ -25,7 +25,7 @@
 
 logger = logging.getLogger(__name__)
 
-FIELD_NAME_RE = re.compile(Body.patterns['field_marker'])
+_FIELD_NAME_RE = re.compile(Body.patterns['field_marker'])
 symbols_re = re.compile(r'([!-\-/:-@\[-`{-~])')  # symbols without dot(0x2e)
 SECTIONING_CHARS = ['=', '-', '~']
 
@@ -77,39 +77,39 @@ def default_role(docname: str, name: str) -> Iterator[None]:
     docutils.unregister_role('')
 
 
-def prepend_prolog(content: StringList, prolog: str) -> None:
-    """Prepend a string to content body as prolog."""
-    if prolog:
-        pos = 0
-        for line in content:
-            if FIELD_NAME_RE.match(line):
-                pos += 1
-            else:
-                break
-
-        if pos > 0:
-            # insert a blank line after docinfo
-            content.insert(pos, '', '<generated>', 0)
+def _prepend_prologue(content: StringList, prologue: str) -> None:
+    """Prepend a string to content body as a prologue."""
+    if not prologue:
+        return
+    pos = 0
+    for line in content:
+        if _FIELD_NAME_RE.match(line):
             pos += 1
+        else:
+            break
 
-        # insert prolog (after docinfo if exists)
-        lineno = 0
-        for lineno, line in enumerate(prolog.splitlines()):
-            content.insert(pos + lineno, line, '<rst_prolog>', lineno)
+    if pos > 0:
+        # insert a blank line after docinfo
+        content.insert(pos, '', '<generated>', 0)
+        pos += 1
 
-        content.insert(pos + lineno + 1, '', '<generated>', 0)
+    # insert prologue (after docinfo if exists)
+    lineno = 0
+    for lineno, line in enumerate(prologue.splitlines()):
+        content.insert(pos + lineno, line, '<rst_prologue>', lineno)
 
+    content.insert(pos + lineno + 1, '', '<generated>', 0)
 
-def append_epilog(content: StringList, epilog: str) -> None:
-    """Append a string to content body as epilog."""
-    if epilog:
-        if len(content) > 0:
-            source, lineno = content.info(-1)
-            # lineno will never be None, since len(content) > 0
-            lineno = cast('int', lineno)
-        else:
-            source = '<generated>'
-            lineno = 0
-        content.append('', source, lineno + 1)
-        for lineno, line in enumerate(epilog.splitlines()):
-            content.append(line, '<rst_epilog>', lineno)
+
+def _append_epilogue(content: StringList, epilogue: str) -> None:
+    """Append a string to content body as an epilogue."""
+    if not epilogue:
+        return
+    if len(content) > 0:
+        source, lineno = content.items[-1]
+    else:
+        source = '<generated>'
+        lineno = 0
+    content.append('', source, lineno + 1)
+    for lineno, line in enumerate(epilogue.splitlines()):
+        content.append(line, '<rst_epilogue>', lineno)

tests/test_markup/test_parser.py

@@ -34,8 +34,8 @@ def test_RSTParser_prolog_epilog(RSTStateMachine, app):
     parser.parse(text, document)
     (content, _), _ = RSTStateMachine().run.call_args
     assert list(content.xitems()) == [
-        ('<rst_prolog>', 0, 'this is rst_prolog'),
-        ('<rst_prolog>', 1, 'hello reST!'),
+        ('<rst_prologue>', 0, 'this is rst_prolog'),
+        ('<rst_prologue>', 1, 'hello reST!'),
         ('<generated>', 0, ''),
         ('dummy.rst', 0, 'hello Sphinx world'),
         ('dummy.rst', 1, 'Sphinx is a document generator'),
@@ -50,8 +50,8 @@ def test_RSTParser_prolog_epilog(RSTStateMachine, app):
         ('dummy.rst', 0, 'hello Sphinx world'),
         ('dummy.rst', 1, 'Sphinx is a document generator'),
         ('dummy.rst', 2, ''),
-        ('<rst_epilog>', 0, 'this is rst_epilog'),
-        ('<rst_epilog>', 1, 'good-bye reST!'),
+        ('<rst_epilogue>', 0, 'this is rst_epilog'),
+        ('<rst_epilogue>', 1, 'good-bye reST!'),
     ]
 
     # expandtabs / convert whitespaces

tests/test_util/test_util_rst.py

@@ -5,7 +5,13 @@
 from docutils.statemachine import StringList
 from jinja2 import Environment
 
-from sphinx.util.rst import append_epilog, escape, heading, prepend_prolog, textwidth
+from sphinx.util.rst import (
+    _append_epilogue,
+    _prepend_prologue,
+    escape,
+    heading,
+    textwidth,
+)
 
 
 def test_escape() -> None:
@@ -15,25 +21,25 @@ def test_escape() -> None:
     assert escape('.. toctree::') == r'\.. toctree\:\:'
 
 
-def test_append_epilog() -> None:
+def test_append_epilogue() -> None:
     epilog = 'this is rst_epilog\ngood-bye reST!'
     content = StringList(
         ['hello Sphinx world', 'Sphinx is a document generator'],
         'dummy.rst',
     )
-    append_epilog(content, epilog)
+    _append_epilogue(content, epilog)
 
     assert list(content.xitems()) == [
         ('dummy.rst', 0, 'hello Sphinx world'),
         ('dummy.rst', 1, 'Sphinx is a document generator'),
         ('dummy.rst', 2, ''),
-        ('<rst_epilog>', 0, 'this is rst_epilog'),
-        ('<rst_epilog>', 1, 'good-bye reST!'),
+        ('<rst_epilogue>', 0, 'this is rst_epilog'),
+        ('<rst_epilogue>', 1, 'good-bye reST!'),
     ]
 
 
-def test_prepend_prolog() -> None:
-    prolog = 'this is rst_prolog\nhello reST!'
+def test_prepend_prologue() -> None:
+    prologue = 'this is rst_prolog\nhello reST!'
     content = StringList(
         [
             ':title: test of SphinxFileInput',
@@ -44,14 +50,14 @@ def test_prepend_prolog() -> None:
         ],
         'dummy.rst',
     )
-    prepend_prolog(content, prolog)
+    _prepend_prologue(content, prologue)
 
     assert list(content.xitems()) == [
         ('dummy.rst', 0, ':title: test of SphinxFileInput'),
         ('dummy.rst', 1, ':author: Sphinx team'),
         ('<generated>', 0, ''),
-        ('<rst_prolog>', 0, 'this is rst_prolog'),
-        ('<rst_prolog>', 1, 'hello reST!'),
+        ('<rst_prologue>', 0, 'this is rst_prolog'),
+        ('<rst_prologue>', 1, 'hello reST!'),
         ('<generated>', 0, ''),
         ('dummy.rst', 2, ''),
         ('dummy.rst', 3, 'hello Sphinx world'),
@@ -60,43 +66,43 @@ def test_prepend_prolog() -> None:
 
 
 def test_prepend_prolog_with_CR() -> None:
-    # prolog having CR at tail
-    prolog = 'this is rst_prolog\nhello reST!\n'
+    # prologue having CR at tail
+    prologue = 'this is rst_prolog\nhello reST!\n'
     content = StringList(
         ['hello Sphinx world', 'Sphinx is a document generator'],
         'dummy.rst',
     )
-    prepend_prolog(content, prolog)
+    _prepend_prologue(content, prologue)
 
     assert list(content.xitems()) == [
-        ('<rst_prolog>', 0, 'this is rst_prolog'),
-        ('<rst_prolog>', 1, 'hello reST!'),
+        ('<rst_prologue>', 0, 'this is rst_prolog'),
+        ('<rst_prologue>', 1, 'hello reST!'),
         ('<generated>', 0, ''),
         ('dummy.rst', 0, 'hello Sphinx world'),
         ('dummy.rst', 1, 'Sphinx is a document generator'),
     ]
 
 
 def test_prepend_prolog_without_CR() -> None:
-    # prolog not having CR at tail
-    prolog = 'this is rst_prolog\nhello reST!'
+    # prologue not having CR at tail
+    prologue = 'this is rst_prolog\nhello reST!'
     content = StringList(
         ['hello Sphinx world', 'Sphinx is a document generator'],
         'dummy.rst',
     )
-    prepend_prolog(content, prolog)
+    _prepend_prologue(content, prologue)
 
     assert list(content.xitems()) == [
-        ('<rst_prolog>', 0, 'this is rst_prolog'),
-        ('<rst_prolog>', 1, 'hello reST!'),
+        ('<rst_prologue>', 0, 'this is rst_prolog'),
+        ('<rst_prologue>', 1, 'hello reST!'),
         ('<generated>', 0, ''),
         ('dummy.rst', 0, 'hello Sphinx world'),
         ('dummy.rst', 1, 'Sphinx is a document generator'),
     ]
 
 
 def test_prepend_prolog_with_roles_in_sections() -> None:
-    prolog = 'this is rst_prolog\nhello reST!'
+    prologue = 'this is rst_prolog\nhello reST!'
     content = StringList(
         [
             ':title: test of SphinxFileInput',
@@ -109,14 +115,14 @@ def test_prepend_prolog_with_roles_in_sections() -> None:
         ],
         'dummy.rst',
     )
-    prepend_prolog(content, prolog)
+    _prepend_prologue(content, prologue)
 
     assert list(content.xitems()) == [
         ('dummy.rst', 0, ':title: test of SphinxFileInput'),
         ('dummy.rst', 1, ':author: Sphinx team'),
         ('<generated>', 0, ''),
-        ('<rst_prolog>', 0, 'this is rst_prolog'),
-        ('<rst_prolog>', 1, 'hello reST!'),
+        ('<rst_prologue>', 0, 'this is rst_prolog'),
+        ('<rst_prologue>', 1, 'hello reST!'),
         ('<generated>', 0, ''),
         ('dummy.rst', 2, ''),
         ('dummy.rst', 3, ':mod:`foo`'),
@@ -128,13 +134,13 @@ def test_prepend_prolog_with_roles_in_sections() -> None:
 
 def test_prepend_prolog_with_roles_in_sections_with_newline() -> None:
     # prologue with trailing line break
-    prolog = 'this is rst_prolog\nhello reST!\n'
+    prologue = 'this is rst_prolog\nhello reST!\n'
     content = StringList([':mod:`foo`', '-' * 10, '', 'hello'], 'dummy.rst')
-    prepend_prolog(content, prolog)
+    _prepend_prologue(content, prologue)
 
     assert list(content.xitems()) == [
-        ('<rst_prolog>', 0, 'this is rst_prolog'),
-        ('<rst_prolog>', 1, 'hello reST!'),
+        ('<rst_prologue>', 0, 'this is rst_prolog'),
+        ('<rst_prologue>', 1, 'hello reST!'),
         ('<generated>', 0, ''),
         ('dummy.rst', 0, ':mod:`foo`'),
         ('dummy.rst', 1, '----------'),
@@ -145,13 +151,13 @@ def test_prepend_prolog_with_roles_in_sections_with_newline() -> None:
 
 def test_prepend_prolog_with_roles_in_sections_without_newline() -> None:
     # prologue with no trailing line break
-    prolog = 'this is rst_prolog\nhello reST!'
+    prologue = 'this is rst_prolog\nhello reST!'
     content = StringList([':mod:`foo`', '-' * 10, '', 'hello'], 'dummy.rst')
-    prepend_prolog(content, prolog)
+    _prepend_prologue(content, prologue)
 
     assert list(content.xitems()) == [
-        ('<rst_prolog>', 0, 'this is rst_prolog'),
-        ('<rst_prolog>', 1, 'hello reST!'),
+        ('<rst_prologue>', 0, 'this is rst_prolog'),
+        ('<rst_prologue>', 1, 'hello reST!'),
         ('<generated>', 0, ''),
         ('dummy.rst', 0, ':mod:`foo`'),
         ('dummy.rst', 1, '----------'),