diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/extdev/parserapi.rst | 38 |
1 files changed, 38 insertions, 0 deletions
diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst new file mode 100644 index 0000000..c5db2ac --- /dev/null +++ b/doc/extdev/parserapi.rst @@ -0,0 +1,38 @@ +.. _parser-api: + +Parser API +========== + +`The docutils documentation describes`__ parsers as follows: + + The Parser analyzes the input document and creates a node tree + representation. + +__ https://docutils.sourceforge.io/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_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 +: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 + :members: |