Parser API
**********

The docutils documentation describes parsers as follows:

   The Parser analyzes the input document and creates a node tree
   representation.

In Sphinx, the parser modules works as same as docutils.  The parsers
are registered to Sphinx by extensions using Application APIs;
"Sphinx.add_source_suffix()" and "Sphinx.add_source_parser()".

The *source suffix* is a mapping from file suffix to file type.  For
example, ".rst" file is mapped to "'restructuredtext'" type.  Sphinx
uses the file type to looking for parsers from registered list.  On
searching, Sphinx refers to the "Parser.supported" attribute and picks
up a parser which contains the file type in the attribute.

The users can override the source suffix mappings using
"source_suffix" like following:

   # a mapping from file suffix to file types
   source_suffix = {
       '.rst': 'restructuredtext',
       '.md': 'markdown',
   }

You should indicate file types your parser supports. This will allow
users to configure their settings appropriately.

class sphinx.parsers.Parser

   A base class of source parsers.  The additional parsers should
   inherit 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 ("sphinx.application.Sphinx")

   self.config
      The config object ("sphinx.config.Config")

   self.env
      The environment object ("sphinx.environment.BuildEnvironment")

   self.warn()
      Emit a warning. (Same as "sphinx.application.Sphinx.warn()")

   self.info()
      Emit a informational message. (Same as
      "sphinx.application.Sphinx.info()")

   Deprecated since version 1.6: "warn()" and "info()" is deprecated.
   Use "sphinx.util.logging" instead.
