blob: c5db2ac979253dcf4df86a9708e9beb2ab4b8181 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
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:
|
