Add sphinx.testing.restructuredtext.parse()

CHANGES

@@ -26,6 +26,8 @@ Bugs fixed
 Testing
 --------
 
+* Add a helper function: ``sphinx.testing.restructuredtext.parse()``
+
 Release 2.0.0 beta1 (in development)
 ====================================
 

sphinx/testing/restructuredtext.py

@@ -0,0 +1,38 @@
+"""
+    sphinx.testing.restructuredtext
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from os import path
+
+from docutils.core import publish_doctree
+
+from sphinx.io import SphinxStandaloneReader
+from sphinx.parsers import RSTParser
+from sphinx.util.docutils import sphinx_domains
+
+
+if False:
+    # For type annotation
+    from docutils import nodes  # NOQA
+    from sphinx.application import Sphinx  # NOQA
+
+
+def parse(app, text, docname='index'):
+    # type: (Sphinx, str, str) -> nodes.document
+    """Parse a string as reStructuredText with Sphinx application."""
+    try:
+        app.env.temp_data['docname'] = docname
+        parser = RSTParser()
+        parser.set_application(app)
+        with sphinx_domains(app.env):
+            return publish_doctree(text, path.join(app.srcdir, docname + '.rst'),
+                                   reader=SphinxStandaloneReader(app),
+                                   parser=parser,
+                                   settings_overrides={'env': app.env,
+                                                       'gettext_compact': True})
+    finally:
+        app.env.temp_data.pop('docname', None)

tests/test_directive_other.py

@@ -10,25 +10,12 @@
 
 import pytest
 from docutils import nodes
-from docutils.core import publish_doctree
 
 from sphinx import addnodes
-from sphinx.io import SphinxStandaloneReader
-from sphinx.parsers import RSTParser
+from sphinx.testing import restructuredtext
 from sphinx.testing.util import assert_node
 
 
-def parse(app, docname, text):
-    app.env.temp_data['docname'] = docname
-    parser = RSTParser()
-    parser.set_application(app)
-    return publish_doctree(text, app.srcdir / docname + '.rst',
-                           reader=SphinxStandaloneReader(app),
-                           parser=parser,
-                           settings_overrides={'env': app.env,
-                                               'gettext_compact': True})
-
-
 @pytest.mark.sphinx(testroot='toctree-glob')
 def test_toctree(app):
     text = (".. toctree::\n"
@@ -38,7 +25,7 @@ def test_toctree(app):
             "   baz\n")
 
     app.env.find_files(app.config, app.builder)
-    doctree = parse(app, 'index', text)
+    doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(doctree[0][0],
                 entries=[(None, 'foo'), (None, 'bar/index'), (None, 'baz')],
@@ -55,7 +42,7 @@ def test_relative_toctree(app):
             "   ../quux\n")
 
     app.env.find_files(app.config, app.builder)
-    doctree = parse(app, 'bar/index', text)
+    doctree = restructuredtext.parse(app, text, 'bar/index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(doctree[0][0],
                 entries=[(None, 'bar/bar_1'), (None, 'bar/bar_2'), (None, 'bar/bar_3'),
@@ -72,7 +59,7 @@ def test_toctree_urls_and_titles(app):
             "   The BAR <bar/index>\n")
 
     app.env.find_files(app.config, app.builder)
-    doctree = parse(app, 'index', text)
+    doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(doctree[0][0],
                 entries=[('Sphinx', 'https://www.sphinx-doc.org/'),
@@ -89,7 +76,7 @@ def test_toctree_glob(app):
             "   *\n")
 
     app.env.find_files(app.config, app.builder)
-    doctree = parse(app, 'index', text)
+    doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(doctree[0][0],
                 entries=[(None, 'baz'), (None, 'foo'), (None, 'quux')],
@@ -103,7 +90,7 @@ def test_toctree_glob(app):
             "   *\n")
 
     app.env.find_files(app.config, app.builder)
-    doctree = parse(app, 'index', text)
+    doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(doctree[0][0],
                 entries=[(None, 'foo'), (None, 'baz'), (None, 'quux')],
@@ -117,7 +104,7 @@ def test_toctree_glob(app):
             "   foo\n")
 
     app.env.find_files(app.config, app.builder)
-    doctree = parse(app, 'index', text)
+    doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(doctree[0][0],
                 entries=[(None, 'baz'), (None, 'foo'), (None, 'quux'), (None, 'foo')],
@@ -132,7 +119,7 @@ def test_toctree_glob_and_url(app):
             "   https://example.com/?q=sphinx\n")
 
     app.env.find_files(app.config, app.builder)
-    doctree = parse(app, 'index', text)
+    doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(doctree[0][0],
                 entries=[(None, 'https://example.com/?q=sphinx')],
@@ -147,7 +134,7 @@ def test_toctree_twice(app):
             "   foo\n")
 
     app.env.find_files(app.config, app.builder)
-    doctree = parse(app, 'index', text)
+    doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(doctree[0][0],
                 entries=[(None, 'foo'), (None, 'foo')],