diff options
Diffstat (limited to 'doc/extdev/parserapi.rst')
| -rw-r--r-- | doc/extdev/parserapi.rst | 29 |
1 files changed, 29 insertions, 0 deletions
diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst index 7008a15a8..e71661b2e 100644 --- a/doc/extdev/parserapi.rst +++ b/doc/extdev/parserapi.rst @@ -3,6 +3,35 @@ Parser API ========== +`The docutils documentation describes`__ parsers as follows: + + The Parser analyzes the input document and creates a node tree + representation. + +__ http://docutils.sourceforge.net/docs/dev/hacking.html#parsing-the-document + +In Sphinx, the parser modules works as same as docutils. The parsers are +registered to Sphinx by extensions using Application APIs; +:meth:`Sphinx.add_source_suffix()` and :meth:`Sphinx.add_source_parsers()`. + +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 +:confval:`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. + .. module:: sphinx.parsers .. autoclass:: Parser |