Merge pull request #2207 from tk0miya/baseclass_for_parsers

Add sphinx.parsers.Parser class; a base class for new parsers

doc/config.rst

@@ -96,8 +96,11 @@ General configuration
 
    If given, a dictionary of parser classes for different source suffices.  The
    keys are the suffix, the values can be either a class or a string giving a
-   fully-qualified name of a parser class.  Files with a suffix that is not in
-   the dictionary will be parsed with the default reStructuredText parser.
+   fully-qualified name of a parser class.  The parser class can be either
+   ``docutils.parsers.Parser`` or :class:`sphinx.parsers.Parser`.  Files with a
+   suffix that is not in the dictionary will be parsed with the default
+   reStructuredText parser.
+
 
    For example::
 

doc/extdev/index.rst

@@ -52,4 +52,5 @@ APIs used for writing extensions
    builderapi
    markupapi
    domainapi
+   parserapi
    nodes

doc/extdev/parserapi.rst

@@ -0,0 +1,8 @@
+.. _parser-api:
+
+Parser API
+==========
+
+.. module:: sphinx.parsers
+
+.. autoclass:: Parser

sphinx/environment.py

@@ -105,13 +105,16 @@ class SphinxStandaloneReader(standalone.Reader):
                   DefaultSubstitutions, MoveModuleTargets, HandleCodeBlocks,
                   AutoNumbering, SortIds, RemoveTranslatableInline]
 
-    def __init__(self, parsers={}, *args, **kwargs):
+    def __init__(self, app, parsers={}, *args, **kwargs):
         standalone.Reader.__init__(self, *args, **kwargs)
         self.parser_map = {}
         for suffix, parser_class in parsers.items():
             if isinstance(parser_class, string_types):
                 parser_class = import_object(parser_class, 'source parser')
-            self.parser_map[suffix] = parser_class()
+            parser = parser_class()
+            if hasattr(parser, 'set_application'):
+                parser.set_application(app)
+            self.parser_map[suffix] = parser
 
     def read(self, source, parser, settings):
         self.source = source
@@ -776,7 +779,7 @@ class BuildEnvironment:
         codecs.register_error('sphinx', self.warn_and_replace)
 
         # publish manually
-        reader = SphinxStandaloneReader(parsers=self.config.source_parsers)
+        reader = SphinxStandaloneReader(self.app, parsers=self.config.source_parsers)
         pub = Publisher(reader=reader,
                         writer=SphinxDummyWriter(),
                         destination_class=NullOutput)

sphinx/parsers.py

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.parsers
+    ~~~~~~~~~~~~~~
+
+    A Base class for additional parsers.
+
+    :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import docutils.parsers
+
+
+class Parser(docutils.parsers.Parser):
+    """
+    A base class of source parsers.  The additonal parsers should inherits this class instead
+    of ``docutils.parsers.Parser``.  Compared with ``docutils.parsers.Parser``, this class
+    improves accessibility to Sphinx APIs.
+
+    The subclasses can access following objects and functions:
+
+    self.app
+        The application object (:class:`sphinx.application.Sphinx`)
+    self.config
+        The config object (:class:`sphinx.config.Config`)
+    self.env
+        The environment object (:class:`sphinx.environment.BuildEnvironment`)
+    self.warn()
+        Emit a warning. (Same as :meth:`sphinx.application.Sphinx.warn()`)
+    self.info()
+        Emit a informational message. (Same as :meth:`sphinx.application.Sphinx.info()`)
+    """
+
+    def set_application(self, app):
+        """set_application will be called from Sphinx to set app and other instance variables
+
+        :param sphinx.application.Sphinx app: Sphinx application object
+        """
+        self.app = app
+        self.config = app.config
+        self.env = app.env
+        self.warn = app.warn
+        self.info = app.info