DocutilsタグAPI

本節では，RESTタグ要素(役割とコマンド)を付加するためのAPIについて述べる.

役柄

指令

指令は派生したものから派生する. docutils.parsers.rst.Directive それがそうです。拡張子を使用して登録しなければなりません Sphinx.add_directive() あるいは…。 Sphinx.add_directive_to_domain() それがそうです。

class docutils.parsers.rst.Directive[ソース]

新しい命令のタグ付け文法は、以下の5つのクラス属性によって決定される：

required_arguments = 0

必要な命令パラメータ数.

optional_arguments = 0

パラメータを必要としたオプションパラメータ数.

final_argument_whitespace = False

最後のパラメータにスペースを含めてもいいですか？

option_spec = None

オプション名のベリファイア関数へのマッピング。

オプション検証関数は、単一のパラメータ、すなわちオプションパラメータ(またはオプションパラメータ)を受け入れる None 与えられていない場合)、それを検証するか、または正しい形式に変換すべきである。彼らは向上しました ValueError あるいは…。 TypeError 失敗を示す。

いくつかの事前定義された有用なベリファイアがある。 docutils.parsers.rst.directives モジュールです。

has_content = False

指示は内容を持っていてもいいですか？

新しい指令は実現しなければならない run() 方法：

run()[ソース]

この方法は、コマンドパラメータ、オプション、およびコンテンツを処理し、コマンドに遭遇した位置で文書木に挿入されるDocutils/Sphinxノードリストを返さなければならない。

命令上に常に設定されているインスタンス属性は、以下のことを含む。

name

命令名(複数の名前の下に同一の命令クラスを登録する際に有用である).

arguments

命令のパラメータをリスト形式で提供する.

options

コマンドに提供されるオプションは、オプション名を検証/変換の値にマッピングする辞書として提供される。

content

命令内容(与えられた場合)を ViewList それがそうです。

lineno

指示が現れた絶対行番号。これはいつも役に立つ値ではない srcline 代わりに。

content_offset

命令内容の内部オフセット.呼び出している nested_parse (下記参照)。

block_text

命令全体を含む文字列.

state
state_machine

解析の状態と状態機械を制御する.使用する nested_parse それがそうです。

ViewLists

Docutilsはクラス中の文書ソース行を表す. docutils.statemachine.ViewList それがそうです。これは、まず、スライスが元のリストを作成するビューであり、ソース行番号に関する情報も含む拡張機能を有するリストである。

♪the Directive.content 属性はビューリストである.RESTに解析するコンテンツを生成する場合は，自分でViewListを作成しなければならない.コンテンツ生成にとって重要なのは，以下の点である.

  • 構造関数は，文字列(行)とソース(文書)名のリストを受け取る.

  • ♪the .append() メソッドは、1行と1つのソース名を受け取ります。

コマンド内容をRESTに解析する

多くの指示は解析されなければならないより多くの標識を含むだろう。そのために、お使いください Directive.run() 方法：

  • self.state.nested_parse

  • sphinx.util.nodes.nested_parse_with_titles() --これにより、解析されたコンテンツにタイトルを表示することができます。

これら2つのAPIはいずれもコンテンツを所与のノードに解析する.これらの使い方は以下のとおりである.

node = docutils.nodes.paragraph()
# either
nested_parse_with_titles(self.state, self.result, node)
# or
self.state.nested_parse(self.result, 0, node)

注釈

sphinx.util.docutils.switch_source_input() NESTED_PARSE中に宛先ファイルの変更が許可されます。それは内容を混ぜるのに有用だ。例えば sphinx. ext.autodoc これを用いて文書文字列を解析する：

from sphinx.util.docutils import switch_source_input

# Switch source_input between parsing content.
# Inside this context, all parsing errors and warnings are reported as
# happened in new source_input (in this case, ``self.result``).
with switch_source_input(self.state, self.result):
    node = docutils.nodes.paragraph()
    self.state.nested_parse(self.result, 0, node)

バージョン 1.7 で非推奨: ライオンの顔像まで-1.6 sphinx.ext.autodoc.AutodocReporter この目的に用いる。現在これは switch_source_input() それがそうです。

パッケージノードが必要でない場合は、任意の具体的なノードタイプを使用して返すことができます。 node.children 指示によると。

参考

Creating directives Docutils文書の使い方