Merge pull request #3581 from eric-wieser/patch-1

Fix issues with trailing underscores in heading names

sphinx/apidoc.py

@@ -25,6 +25,7 @@ from fnmatch import fnmatch
 
 from sphinx.util.osutil import FileAvoidWrite, walk
 from sphinx import __display_version__
+from sphinx.util import rst
 
 # automodule options
 if 'SPHINX_APIDOC_OPTIONS' in os.environ:
@@ -67,8 +68,10 @@ def write_file(name, text, opts):
             f.write(text)
 
 
-def format_heading(level, text):
+def format_heading(level, text, escape=True):
     """Create a heading of <level> [1, 2 or 3 supported]."""
+    if escape:
+        text = rst.escape(text)
     underlining = ['=', '-', '~', ][level - 1] * len(text)
     return '%s\n%s\n\n' % (text, underlining)
 
@@ -149,7 +152,7 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs, is_
 
 def create_modules_toc_file(modules, opts, name='modules'):
     """Create the module's index."""
-    text = format_heading(1, '%s' % opts.header)
+    text = format_heading(1, '%s' % opts.header, escape=False)
     text += '.. toctree::\n'
     text += '   :maxdepth: %s\n\n' % opts.maxdepth
 

tests/roots/test-apidoc-trailing-underscore/package_/__init__.py

@@ -0,0 +1 @@
+""" A package with trailing underscores """

tests/roots/test-apidoc-trailing-underscore/package_/module_.py

@@ -0,0 +1,7 @@
+""" A module with a trailing underscore """
+
+class SomeClass_:
+    """ A class with a trailing underscore """
+
+def some_function_(some_arg_):
+    """ A function with a trailing underscore in name and argument """

tests/test_apidoc.py

@@ -60,7 +60,7 @@ def test_simple(make_app, apidoc):
 
 
 @pytest.mark.apidoc(
-    coderoot=(rootdir / 'root' / 'pep_0420'),
+    coderoot=(rootdir / 'roots' / 'test-apidoc-pep420'),
     options=["--implicit-namespaces"],
 )
 def test_pep_0420_enabled(make_app, apidoc):
@@ -71,13 +71,11 @@ def test_pep_0420_enabled(make_app, apidoc):
 
     with open(outdir / 'a.b.c.rst') as f:
         rst = f.read()
-        assert "a.b.c package\n" in rst
         assert "automodule:: a.b.c.d\n" in rst
         assert "automodule:: a.b.c\n" in rst
 
     with open(outdir / 'a.b.x.rst') as f:
         rst = f.read()
-        assert "a.b.x namespace\n" in rst
         assert "automodule:: a.b.x.y\n" in rst
         assert "automodule:: a.b.x\n" not in rst
 
@@ -86,8 +84,20 @@ def test_pep_0420_enabled(make_app, apidoc):
     print(app._status.getvalue())
     print(app._warning.getvalue())
 
+    builddir = outdir / '_build' / 'text'
+    assert (builddir / 'a.b.c.txt').isfile()
+    assert (builddir / 'a.b.x.txt').isfile()
 
-@pytest.mark.apidoc(coderoot=(rootdir / 'root' / 'pep_0420'))
+    with open(builddir / 'a.b.c.txt') as f:
+        txt = f.read()
+        assert "a.b.c package\n" in txt
+
+    with open(builddir / 'a.b.x.txt') as f:
+        txt = f.read()
+        assert "a.b.x namespace\n" in txt
+
+
+@pytest.mark.apidoc(coderoot=(rootdir / 'roots' / 'test-apidoc-pep420'))
 def test_pep_0420_disabled(make_app, apidoc):
     outdir = apidoc.outdir
     assert (outdir / 'conf.py').isfile()
@@ -100,7 +110,8 @@ def test_pep_0420_disabled(make_app, apidoc):
     print(app._warning.getvalue())
 
 
-@pytest.mark.apidoc(coderoot=(rootdir / 'root' / 'pep_0420' / 'a' / 'b'))
+@pytest.mark.apidoc(
+    coderoot=(rootdir / 'roots' / 'test-apidoc-pep420' / 'a' / 'b'))
 def test_pep_0420_disabled_top_level_verify(make_app, apidoc):
     outdir = apidoc.outdir
     assert (outdir / 'conf.py').isfile()
@@ -118,6 +129,23 @@ def test_pep_0420_disabled_top_level_verify(make_app, apidoc):
     print(app._status.getvalue())
     print(app._warning.getvalue())
 
+@pytest.mark.apidoc(
+    coderoot=(rootdir / 'roots' / 'test-apidoc-trailing-underscore'))
+def test_trailing_underscore(make_app, apidoc):
+    outdir = apidoc.outdir
+    assert (outdir / 'conf.py').isfile()
+    assert (outdir / 'package_.rst').isfile()
+
+    app = make_app('text', srcdir=outdir)
+    app.build()
+    print(app._status.getvalue())
+    print(app._warning.getvalue())
+
+    builddir = outdir / '_build' / 'text'
+    with open(builddir / 'package_.txt') as f:
+        rst = f.read()
+        assert "package_ package\n" in rst
+        assert "package_.module_ module\n" in rst
 
 @pytest.mark.apidoc(
     coderoot=(rootdir / 'root'),