パーサ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 withdocutils.parsers.Parser
, this class improves accessibility to Sphinx APIs.このクラスを継承すると以下のメンバ変数やメソッドを利用できます。
- self.app
アプリケーションオブジェクト (
sphinx.application.Sphinx
)- self.config
設定オブジェクト (
sphinx.config.Config
)- self.env
ビルド環境オブジェクト (
sphinx.environment.BuildEnvironment
)- self.warn()
警告を発生させます (
sphinx.application.Sphinx.warn()
と同じメソッドです)。- self.info()
インフォログを出力します (
sphinx.application.Sphinx.info()
と同じメソッドです)。
バージョン 1.6 で非推奨:
warn()
andinfo()
is deprecated. Usesphinx.util.logging
instead.バージョン 3.0 で非推奨: parser.app is deprecated.