👌 Allow access to the parser during the read phase (#12361)

This commit allows access to the `Parser` instance during the read phase, using the read-only property `BuildEnvironment.parser`.

This aims to allow for parser agnostic logic within roles and directives,
as opposed to hard-coding for implementation details of the default docutils `RSTParser`.

CHANGES.rst

@@ -13,6 +13,9 @@ Deprecated
 Features added
 --------------
 
+* #12361: Allow the parser instance to be accessed within directives
+  with ``self.env.parser``. Patch by Chris Sewell.
+
 * #11165: Support the `officially recommended`_ ``.jinja`` suffix for template
   files.
   Patch by James Addison and Adam Turner

sphinx/builders/__init__.py

@@ -485,6 +485,7 @@ class Builder:
         filename = self.env.doc2path(docname)
         filetype = get_filetype(self.app.config.source_suffix, filename)
         publisher = self.app.registry.get_publisher(self.app, filetype)
+        self.env.temp_data['_parser'] = publisher.parser
         # record_dependencies is mutable even though it is in settings,
         # explicitly re-initialise for each document
         publisher.settings.record_dependencies = DependencyList()

sphinx/environment/__init__.py

@@ -28,6 +28,7 @@ if TYPE_CHECKING:
 
     from docutils import nodes
     from docutils.nodes import Node
+    from docutils.parsers import Parser
 
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
@@ -549,6 +550,11 @@ class BuildEnvironment:
         """Returns the docname of the document currently being parsed."""
         return self.temp_data['docname']
 
+    @property
+    def parser(self) -> Parser:
+        """Returns the parser being used for to parse the current document."""
+        return self.temp_data['_parser']
+
     def new_serialno(self, category: str = '') -> int:
         """Return a serial number, e.g. for index entry targets.