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 sphinx core runtime objects (app, config
   and env).

   set_application(app: Sphinx) -> None

      set_application will be called from Sphinx to set app and other
      instance variables

      Parameters:
         **app** (*sphinx.application.Sphinx*) -- Sphinx application
         object

   config: Config

      The config object

   env: BuildEnvironment

      The environment object
