Sphinx

# 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