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 the 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 an info message. (Same as sphinx.application.Sphinx.info())

1.6 版后已移除: warn() and info() is deprecated. Use sphinx.util.logging instead.

3.0 版后已移除: parser.app is deprecated.