ドメインAPI¶
- class sphinx.domains.Domain(env: BuildEnvironment)[ソース]¶
ドメインというのは、似たような特性を持つオブジェクトごとに用意された「オブジェクト」説明ディレクティブと、それらに対応してリファレンスを作成するロールを集めたものです。例えば、Pythonのモジュール、クラス、関数、テンプレート言語であればエレメント、Sphinxであればロールとディレクティブなどです。
ドメインごとに、既存のオブジェクトの情報や、それらへの参照の仕方などを個別の領域に保存します。保存先は self.data で、辞書でなければなりません。また、Sphinxの一部として決まったフォーマットでオブジェクトの情報を公開するための関数や、ユーザが参照できるようにしたり、ドメインごとの方法でオブジェクトを探索する関数をいくつか実装する必要があります。
About self.data: since all object and cross-referencing information is stored on a BuildEnvironment instance, the domain.data object is also stored in the env.domaindata dict under the key domain.name. Before the build process starts, every active domain is instantiated and given the environment object; the domaindata dict must then either be nonexistent or a dictionary whose 'version' key is equal to the domain class'
data_version
attribute. Otherwise, OSError is raised and the pickled environment is discarded.- directive(name: str) Callable | None [ソース]¶
self.name
で指定されたドメイン付きで、完全な名前('ドメイン:名前')で登録されたディレクティブ を与える、ディレクティブアダプタークラスを返します。
- get_objects() Iterable[tuple[str, str, str, str, str, int]] [ソース]¶
Return an iterable of "object descriptions".
Object descriptions are tuples with six items:
name
Fully qualified name.
dispname
Name to display when searching/linking.
type
Object type, a key in
self.object_types
.docname
The document where it is to be found.
anchor
The anchor name for the object.
priority
How "important" the object is (determines placement in search results). One of:
1
Default priority (placed before full-text matches).
0
Object is important (placed before default-priority objects).
2
Object is unimportant (placed after full-text matches).
-1
Object should not show up in search at all.
- merge_domaindata(docnames: list[str], otherdata: dict[str, Any]) None [ソース]¶
Merge in data regarding docnames from a different domaindata inventory (coming from a subprocess in parallel builds).
- process_doc(env: BuildEnvironment, docname: str, document: nodes.document) None [ソース]¶
ドキュメントが環境によって読まれた後で、そのドキュメントを処理します。
- process_field_xref(pnode: pending_xref) None [ソース]¶
Process a pending xref created in a doc field. For example, attach information about the current scope.
- resolve_any_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: pending_xref, contnode: Element) list[tuple[str, Element]] [ソース]¶
target を持つ、
pending_xref
(未解決のクロスリファレンス) node の参照先の解決を行います。"any", もしくはそれに類似するロールに基づくリファレンスは、タイプがわからないということを意味します。もしくは、引数が
resolve_xref()
と同様のものであるかです。このメソッドはタプルを要素に持つリストを返す必要があります(リストは空の可能性があります)。各要素はタプルで、
('domain:role', newnode)
の形式です。'domain:role'
は'py:func'
のようなnewnodeを生成するときに使われるロール名で、newnode
はresolve_xref()
の返値と同じです。バージョン 1.3 で追加.
- resolve_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, typ: str, target: str, node: pending_xref, contnode: Element) Element | None [ソース]¶
typ 型と、 target を持つ、
pending_xref
(未解決のクロスリファレンス) node の参照先の解決を行います。このメソッドは、xrefノードと置き換えるための、新しいノードを返さなければなりません。また、この新しいノードには、クロスリファレンスのマークアップのコンテンツである、 contnode を含めます。
If no resolution can be found, None can be returned; the xref node will then given to the
missing-reference
event, and if that yields no resolution, replaced by contnode.The method can also raise
sphinx.environment.NoUri
to suppress themissing-reference
event being emitted.
- data_version = 0¶
データのバージョンです。もしも self.data 内のフォーマットを変更したときには、この数字を上げてください。
- enumerable_nodes: dict[type[Node], tuple[str, TitleGetter | None]] = {}¶
node_class -> (enum_node_type, title_getter)
- label = ''¶
ドメインのラベルです。
name
よりも長く、説明的な名前です。メッセージ内で利用されます。
- name = ''¶
ドメイン名です。なるべく短く、重複のない名前にする必要があります。
- class sphinx.domains.ObjType(lname: str, *roles: Any, **attrs: Any)[ソース]¶
ObjTypeは、そのドメインでドキュメントを書くことができる、オブジェクトの種類に対する説明ユニットです。Domainのサブクラスの object_types の辞書の中に、オブジェクト名と、このクラスのインスタンスのマッピングが保持されます。
コンストラクタ引数
lname: ローカライズされた型名
roles: この型を参照できる、すべてのロール
attrs: オブジェクトの属性。現在では、全文検索インデックス内での、オブジェクトの優先順位(
Domain.get_objects()
参照)のみが定義されています。
- class sphinx.domains.Index(domain: Domain)[ソース]¶
Indexは、ドメインに特化した索引のための説明を行うクラスです。ドメインに対する索引を追加する場合には、Indexのサブクラスを作り、3つの名前属性をオーバーライドします:
name is an identifier used for generating file names. It is also used for a hyperlink target for the index. Therefore, users can refer the index page using
ref
role and a string which is combined domain name andname
attribute (ex.:ref:`py-modindex`
).localname は索引のセクションタイトルです。
shortname は索引に対する短い名前です。これは、HTML出力のリレーションバーで使用されます。もしも空であれば、リレーションバーのエントリーは無効化されます。
次に、
generate()
メソッドを提供するようにします。最後に、自分の作ったドメインのDomainクラスが持つ、 indices リストに追加します。拡張機能の中でadd_index_to_domain()
メソッドを呼ぶと、既存のドメインに対して、索引を追加することもできます。バージョン 3.0 で変更: Index pages can be referred by domain name and index name via
ref
role.- abstract generate(docnames: Iterable[str] | None = None) tuple[list[tuple[str, list[IndexEntry]]], bool] [ソース]¶
Get entries for the index.
If
docnames
is given, restrict to entries referring to these docnames.The return value is a tuple of
(content, collapse)
:collapse
A boolean that determines if sub-entries should start collapsed (for output formats that support collapsing sub-entries).
content
:A sequence of
(letter, entries)
tuples, whereletter
is the "heading" for the givenentries
, usually the starting letter, andentries
is a sequence of single entries. Each entry is a sequence[name, subtype, docname, anchor, extra, qualifier, descr]
. The items in this sequence have the following meaning:name
The name of the index entry to be displayed.
subtype
The sub-entry related type. One of:
0
A normal entry.
1
An entry with sub-entries.
2
A sub-entry.
docname
docname where the entry is located.
anchor
Anchor for the entry within
docname
extra
Extra info for the entry.
qualifier
Qualifier for the description.
descr
Description for the entry.
Qualifier and description are not rendered for some output formats such as LaTeX.
- class sphinx.directives.ObjectDescription(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[ソース]¶
Directive to describe a class, function or similar object. Not used directly, but subclassed (in domain-specific directives) to add custom behavior.
- _object_hierarchy_parts(sig_node: desc_signature) tuple[str, ...] [ソース]¶
Returns a tuple of strings, one entry for each part of the object's hierarchy (e.g.
('module', 'submodule', 'Class', 'method')
). The returned tuple is used to properly nest children within parents in the table of contents, and can also be used within the_toc_entry_name()
method.This method must not be used outwith table of contents generation.
- _toc_entry_name(sig_node: desc_signature) str [ソース]¶
Returns the text of the table of contents entry for the object.
This function is called once, in
run()
, to set the name for the table of contents entry (a special attribute_toc_name
is set on the object node, later used inenvironment.collectors.toctree.TocTreeCollector.process_doc().build_toc()
when the table of contents entries are collected).To support table of contents entries for their objects, domains must override this method, also respecting the configuration setting
toc_object_entries_show_parents
. Domains must also override_object_hierarchy_parts()
, with one (string) entry for each part of the object's hierarchy. The result of this method is set on the signature node, and can be accessed assig_node['_toc_parts']
for use within this method. The resulting tuple is also used to properly nest children within parents in the table of contents.An example implementations of this method is within the python domain (
PyObject._toc_entry_name()
). The python domain sets the_toc_parts
attribute within thehandle_signature()
method.
- add_target_and_index(name: ObjDescT, sig: str, signode: desc_signature) None [ソース]¶
Add cross-reference IDs and entries to self.indexnode, if applicable.
name is whatever
handle_signature()
returned.
- after_content() None [ソース]¶
Called after parsing content. Used to reset information about the current directive context on the build environment.
- before_content() None [ソース]¶
Called before parsing content. Used to set information about the current directive context on the build environment.
- get_signatures() list[str] [ソース]¶
Retrieve the signatures to document from the directive arguments. By default, signatures are given as arguments, one per line.
- handle_signature(sig: str, signode: desc_signature) ObjDescT [ソース]¶
Parse the signature sig into individual nodes and append them to signode. If ValueError is raised, parsing is aborted and the whole sig is put into a single desc_name node.
The return value should be a value that identifies the object. It is passed to
add_target_and_index()
unchanged, and otherwise only used to skip duplicates.
- run() list[Node] [ソース]¶
Main directive entry function, called by docutils upon encountering the directive.
This directive is meant to be quite easily subclassable, so it delegates to several additional methods. What it does:
find out if called as a domain-specific directive, set self.domain
create a desc node to fit all description inside
parse standard options, currently no-index
create an index node if needed as self.indexnode
parse all given signatures (as returned by self.get_signatures()) using self.handle_signature(), which should either return a name or raise ValueError
add index entries using self.add_target_and_index()
parse the content and handle doc fields in it
- transform_content(contentnode: desc_content) None [ソース]¶
Called after creating the content through nested parsing, but before the
object-description-transform
event is emitted, and before the info-fields are transformed. Can be used to manipulate the content.
- final_argument_whitespace = True¶
May the final argument contain whitespace?
- has_content = True¶
May the directive have content?
- option_spec: ClassVar[dict[str, Callable[[str], Any]]] = {'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>}¶
Mapping of option names to validator functions.
- optional_arguments = 0¶
Number of optional arguments after the required arguments.
- required_arguments = 1¶
Number of required directive arguments.