アプリケーションAPI

Each Sphinx extension is a Python module with at least a setup() function. This function is called at initialization time with one argument, the application object representing the Sphinx process.

class sphinx.application.Sphinx[ソース]

Sphinxオブジェクトは以下のようなAPIを持っています

拡張のセットアップ

以下のメソッドは通常、拡張機能のsetup()関数の中で呼ばれます。

Sphinx拡張APIの使用法に関するサンプルは、Sphinx標準の sphinx.ext のパッケージの中を見てください。

Sphinx.setup_extension(name)[ソース]

Import and setup a Sphinx extension module.

Load the extension given by the module name. Use this if your extension needs the features provided by another extension. No-op if called twice.

Sphinx.require_sphinx(version)[ソース]

Check the Sphinx version if requested.

version ('1.1' のような、 メジャー.マイナー 形式のバージョン文字列)と、実行しているSphinxのバージョンを比較して、古すぎる場合にはビルドを中断します。

バージョン 1.0 で追加.

Sphinx.connect(event, callback)[ソース]

Register callback to be called when event is emitted.

For details on available core events and the arguments of callback functions, please see Sphinxコアイベント.

このメソッドは "リスナーID" を返します。これは disconnect() を呼んで削除する場合の引き数に使用します。

Sphinx.disconnect(listener_id)[ソース]

Unregister callback by listener_id.

Sphinx.add_builder(builder)[ソース]

Register a new builder.

builder must be a class that inherits from Builder.

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_config_value(name, default, rebuild)[ソース]

Register a configuration value.

This is necessary for Sphinx to recognize new values and set default values accordingly. The name should be prefixed with the extension name, to avoid clashes. The default value can be any Python object. The string value rebuild must be one of those values:

  • 'env' 設定を変更してからビルドをかけると、環境全体が再ビルドされます。

  • 'html' この設定を変更してからビルドをかけた場合、出力がHTMLの時にフル再ビルドされます。

  • '' 設定を変更してもなにも再ビルドに関しては影響を与えません。

バージョン 0.6 で変更: rebuild が単純なブーリアン型('', 'env' に相当)から文字列に変更されました。後方互換性のために、ブーリアン型も受け取ることが可能で、その場合には内部で変換されます。

バージョン 0.4 で変更: If the default value is a callable, it will be called with the config object as its argument in order to get the default value. This can be used to implement config values whose default depends on other values.

Sphinx.add_event(name)[ソース]

Register an event called name.

This is needed to be able to emit it.

Sphinx.set_translator(name, translator_class)[ソース]

Register or override a Docutils translator class.

This is used to register a custom output translator or to replace a builtin translator. This allows extensions to use custom translator and define custom nodes for the translator (see add_node()).

バージョン 1.3 で追加.

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_node(node, **kwds)[ソース]

Register a Docutils node class.

This is necessary for Docutils internals. It may also be used in the future to validate nodes in the parsed documents.

Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers can be given as keyword arguments: the keyword should be one or more of 'html', 'latex', 'text', 'man', 'texinfo' or any other supported translators, the value a 2-tuple of (visit, depart) methods. depart can be None if the visit function raises docutils.nodes.SkipNode. Example:

class math(docutils.nodes.Element): pass

def visit_math_html(self, node):
    self.body.append(self.starttag(node, 'math'))
def depart_math_html(self, node):
    self.body.append('</math>')

app.add_node(math, html=(visit_math_html, depart_math_html))

言うまでも無いことですが、ビジターメソッドを定義しないトランスレータを実行していて、そのメソッドを必要とするドキュメントに遭遇するとトランスレータはエラー停止します。

バージョン 0.5 で変更: ビジター関数を、キーワード引数を使って渡すことができるようになりました。

Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds)[ソース]

Register a Docutils node class as a numfig target.

Sphinx numbers the node automatically. And then the users can refer it using numref.

figtype is a type of enumerable nodes. Each figtypes have individual numbering sequences. As a system figtypes, figure, table and code-block are defined. It is able to add custom nodes to these default figtypes. It is also able to define new custom figtype if new figtype is given.

title_getter is a getter function to obtain the title of node. It takes an instance of the enumerable node, and it must return its title as string. The title is used to the default title of references for ref. By default, Sphinx searches docutils.nodes.caption or docutils.nodes.title from the node as a title.

Other keyword arguments are used for node visitor functions. See the Sphinx.add_node() for details.

バージョン 1.4 で追加.

Sphinx.add_directive(name, func, content, arguments, **options)[ソース]
Sphinx.add_directive(name, directiveclass)[ソース]

Register a Docutils directive.

name must be the prospective directive name. cls is a directive class which inherits docutils.parsers.rst.Directive. For more details, see the Docutils docs .

例えば、 literalinclude というディレクティブを追加する場合には(既に存在していますが)、以下のように書きます:

from docutils.parsers.rst import Directive, directives

class LiteralIncludeDirective(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {
        'class': directives.class_option,
        'name': directives.unchanged,
    }

    def run(self):
        ...

add_directive('literalinclude', LiteralIncludeDirective)

バージョン 0.6 で変更: Docutils 0.5 スタイルのディレクティブクラスをサポートしました。

バージョン 1.8 で非推奨: Docutils 0.4-style (function based) directives support is deprecated.

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_role(name, role)[ソース]

Register a Docutils role.

name must be the role name that occurs in the source, role the role function. Refer to the Docutils documentation for more information.

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_generic_role(name, nodeclass)[ソース]

Register a generic Docutils role.

Docutilsのロールを登録します。このロールは特に何もしませんが、与えられた nodeclass を使ってラップされるようになります。

バージョン 0.6 で追加.

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_domain(domain)[ソース]

Register a domain.

与えられた domain (クラスです。おそらく Domain のサブクラスになるでしょう)をSphinxに知らせます。

バージョン 1.0 で追加.

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_directive_to_domain(domain, name, func, content, arguments, **options)[ソース]
Sphinx.add_directive_to_domain(domain, name, directiveclass)[ソース]

Register a Docutils directive in a domain.

add_directive() と似ていますが、ディレクティブを、 domain で指定されたドメインにのみ追加します。

バージョン 1.0 で追加.

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_role_to_domain(domain, name, role)[ソース]

Register a Docutils role in a domain.

add_role() に似ていますが、 domain で指定されたドメインに、新しいロールを追加します。

バージョン 1.0 で追加.

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_index_to_domain(domain, index)[ソース]

Register a custom index for a domain.

カスタムの index クラスを、 domain で指定されたドメイン名に追加します。 indexIndex のサブクラスでなければなりません。

バージョン 1.0 で追加.

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])[ソース]

Register a new object type.

このメソッドは、クロスリファレンスを作成できる、新しい object 型を追加できる便利なメソッドです。このメソッドは以下のことを行います:

  • Create a new directive (called directivename) for documenting an object. It will automatically add index entries if indextemplate is nonempty; if given, it must contain exactly one instance of %s. See the example below for how the template will be interpreted.

  • rolename で指定された名前を持つ、新しいロールが作成されます。これを使用すると、これらのオブジェクトの説明に対して、クロスリファレンスを張ることができるようになります。

  • parse_node を指定する場合には、文字列と、docutilsのノードを受け取る関数を指定しなければなりません。ノードは、その文字列をパースして得られた子供のノードを受け取ります。この関数はクロスリファレンスと索引のエントリーで使用される名前を返さなければなりません。ここの説明のサンプルを見たい場合には、Sphinxのソースコードの conf.py を参照してください。

  • objname (もし与えられなければ、デフォルトでは directivename と同値になります)は、オブジェクトのタイプ名の名前を付けます。これは、検索結果など、オブジェクトを一覧表示する場合に使用されます。

以下のような関数呼び出しが、カスタムのSphinx拡張の中で行われたとすると:

app.add_object_type('directive', 'dir', 'pair: %s; directive')

ドキュメント内で次のようなマークアップが使用できるようになります:

.. rst:directive:: function

   Document a function.

<...>

See also the :rst:dir:`function` directive.

また、このディレクティブを使用すると、以下のようにindexディレクティブを書いたのと同じ索引が作成されます:

.. index:: pair: function; directive

リファレンスノードのクラスは、 ref_nodeclass を指定しない場合には literal (コードの記述に適したプロポーショナルフォントでレンダリングされる)になります。クラスは、docutilsのノードクラスを設定する必要があります。docutilsのクラスの中で頻繁に使用されるのは docutils.nodes.emphasis あるいは docutils.nodes.strong です。もしも装飾が不要であれば、 docutils.nodes.generated も使用できます。もしテキストをリテラルとして処理したいなら(例えばスマートクォート置換が扶養であれば)、そしてタイプライタースタイルで表示したくないなら、 sphinx.addnodes.literal_emphasissphinx.addnodes.literal_strong を使用してください。

ロールの中身に関しては、標準のSphinxのロールと同じ構文を使用できます(クロスリファレンス文法 参照)。

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')[ソース]

Register a new crossref object type.

このメソッドは ディレクティブの出力が必ず空になることを除けば、 add_object_type() と非常に良く似ています。

これは、セマンティックのターゲットをソースに追加して、カスタムのロールを使用して参照することができるということを意味しています。ただし、 ref のような一般的なものは使用することができません。サンプル:

app.add_crossref_type('topic', 'topic', 'single: %s',
                      docutils.nodes.emphasis)

使用例:

.. topic:: application API

The application API
-------------------

Some random text here.

See also :topic:`this section <application API>`.

もちろん、 topic ディレクティブに続く要素はセクションでなくてもかまいません。

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_transform(transform)[ソース]

Register a Docutils transform to be applied after parsing.

標準のDocutilsの Transform のサブクラスの transform をtransformのリストに追加します。これはSphinxがreST形式のドキュメントをパースした後に適用されます。

priority range categories for Sphinx transforms

Priority

Main purpose in Sphinx

0-99

Fix invalid nodes by docutils. Translate a doctree.

100-299

Preparation

300-399

early

400-699

main

700-799

Post processing. Deadline to modify text and referencing.

800-899

Collect referencing and referenced nodes. Domain processing.

900-999

Finalize and clean up.

refs: Transform Priority Range Categories

Sphinx.add_post_transform(transform)[ソース]

Register a Docutils transform to be applied before writing.

標準のDocutilsの Transform のサブクラスの transform をtransformのリストに追加します。これはSphinxがreST形式のドキュメントを書き出す前に適用されます。

Sphinx.add_js_file(filename, **kwargs)[ソース]

Register a JavaScript file to include in the HTML output.

Add filename to the list of JavaScript files that the default HTML template will include. The filename must be relative to the HTML static path , or a full URI with scheme. The keyword arguments are also accepted for attributes of <script> tag.

サンプル:

app.add_js_file('example.js')
# => <script src="_static/example.js"></script>

app.add_js_file('example.js', async="async")
# => <script src="_static/example.js" async="async"></script>

バージョン 0.5 で追加.

バージョン 1.8 で変更: Renamed from app.add_javascript(). And it allows keyword arguments as attributes of script tag.

Sphinx.add_css_file(filename, **kwargs)[ソース]

Register a stylesheet to include in the HTML output.

Add filename to the list of CSS files that the default HTML template will include. The filename must be relative to the HTML static path, or a full URI with scheme. The keyword arguments are also accepted for attributes of <link> tag.

サンプル:

app.add_css_file('custom.css')
# => <link rel="stylesheet" href="_static/custom.css" type="text/css" />

app.add_css_file('print.css', media='print')
# => <link rel="stylesheet" href="_static/print.css"
#          type="text/css" media="print" />

app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
# => <link rel="alternate stylesheet" href="_static/fancy.css"
#          type="text/css" title="fancy" />

バージョン 1.0 で追加.

バージョン 1.6 で変更: Optional alternate and/or title attributes can be supplied with the alternate (of boolean type) and title (a string) arguments. The default is no title and alternate = False. For more information, refer to the documentation.

バージョン 1.8 で変更: Renamed from app.add_stylesheet(). And it allows keyword arguments as attributes of link tag.

Sphinx.add_latex_package(packagename, options=None)[ソース]

Register a package to include in the LaTeX source code.

Add packagename to the list of packages that LaTeX source code will include. If you provide options, it will be taken to usepackage declaration.

app.add_latex_package('mypackage')
# => \usepackage{mypackage}
app.add_latex_package('mypackage', 'foo,bar')
# => \usepackage[foo,bar]{mypackage}

バージョン 1.3 で追加.

Sphinx.add_lexer(alias, lexer)[ソース]

Register a new lexer for source code.

Use lexer to highlight code blocks with the given language alias.

バージョン 0.6 で追加.

バージョン 2.1 で変更: Take a lexer class as an argument. An instance of lexers are still supported until Sphinx-3.x.

Sphinx.add_autodocumenter(cls)[ソース]

Register a new documenter class for the autodoc extension.

Add cls as a new documenter class for the sphinx.ext.autodoc extension. It must be a subclass of sphinx.ext.autodoc.Documenter. This allows to auto-document new types of objects. See the source of the autodoc module for examples on how to subclass Documenter.

課題

Add real docs for Documenter and subclassing

バージョン 0.6 で追加.

バージョン 2.2 で変更: Add override keyword.

Sphinx.add_autodoc_attrgetter(type, getter)[ソース]

Register a new getattr-like function for the autodoc extension.

Add getter, which must be a function with an interface compatible to the getattr() builtin, as the autodoc attribute getter for objects that are instances of typ. All cases where autodoc needs to get an attribute of a type are then handled by this function instead of getattr().

バージョン 0.6 で追加.

Sphinx.add_search_language(cls)[ソース]

Register a new language for the HTML search index.

言語ごとに、HTMLの全文検索インデックスを構築する、 sphinx.search.SearchLanguage クラスのサブクラスである cls を追加します。このクラスにはどの言語から使われるのかを表す、 lang 属性を持たせる必要があります。詳しくは、 html_search_language を参照してください。

バージョン 1.1 で追加.

Sphinx.add_source_suffix(suffix, filetype)[ソース]

Register a suffix of source files.

Same as source_suffix. The users can override this using the setting.

バージョン 1.8 で追加.

Sphinx.add_source_parser(parser)[ソース]

Register a parser class.

バージョン 1.4 で追加.

バージョン 1.8 で変更: suffix argument is deprecated. It only accepts parser argument. Use add_source_suffix() API to register suffix instead.

バージョン 1.8 で変更: Add override keyword.

Sphinx.add_env_collector(collector)[ソース]

Register an environment collector class.

Refer to Environment Collector API.

バージョン 1.6 で追加.

Sphinx.add_html_theme(name, theme_path)[ソース]

Register a HTML Theme.

The name is a name of theme, and path is a full path to the theme (refs: Distribute your theme as a Python package).

バージョン 1.6 で追加.

Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)[ソース]

Register a math renderer for HTML.

The name is a name of math renderer. Both inline_renderers and block_renderers are used as visitor functions for the HTML writer: the former for inline math node (nodes.math), the latter for block math node (nodes.math_block). Regarding visitor functions, see add_node() for details.

バージョン 1.8 で追加.

Sphinx.add_message_catalog(catalog, locale_dir)[ソース]

Register a message catalog.

The catalog is a name of catalog, and locale_dir is a base path of message catalog. For more details, see sphinx.locale.get_translation().

バージョン 1.8 で追加.

Sphinx.is_parallel_allowed(typ)[ソース]

Check parallel processing is allowed or not.

typ is a type of processing; 'read' or 'write'.

exception sphinx.application.ExtensionError

ここで説明したすべてのメソッドは、もし拡張APIの中で何か想定外のことが発生した時には、この例外を投げます。

イベントの発行

class sphinx.application.Sphinx[ソース]
emit(event, *arguments)[ソース]

Emit event and pass arguments to the callback functions.

Return the return values of all callbacks as a list. Do not emit core Sphinx events in extensions!

emit_firstresult(event, *arguments)[ソース]

Emit event and pass arguments to the callback functions.

Return the result of the first callback that doesn't return None.

バージョン 0.5 で追加.

Sphinx runtime information

The application object also provides runtime information as attributes.

Sphinx.project

Target project. See Project.

Sphinx.srcdir

ソースディレクトリ。

Sphinx.confdir

Directory containing conf.py.

Sphinx.doctreedir

pickle化された doctree を格納するディレクトリ

Sphinx.outdir

Directory for storing built document.

Sphinxコアイベント

These events are known to the core. The arguments shown are given to the registered event handlers. Use Sphinx.connect() in an extension's setup function (note that conf.py can also have a setup function) to connect handlers to the events. Example:

def source_read_handler(app, docname, source):
    print('do something here...')

def setup(app):
    app.connect('source-read', source_read_handler)
builder-inited(app)

ビルダーオブジェクトが作成された時に発行されます。ビルダーオブジェクトは app.builder とすることで参照できます。

config-inited(app, config)

Emitted when the config object has been initialized.

バージョン 1.8 で追加.

env-get-outdated(app, env, added, changed, removed)

ソースファイルが変更されたりして、再読み込みする必要がある場合に発行されます。 added, changed, removed には、ドキュメント名のセットです。さらに追加で読み込み直すべきドキュメントのリストを返すことができます。

バージョン 1.1 で追加.

env-purge-doc(app, env, docname)

ソースファイルが削除されたり、新たに読み込まる場合など、環境の中に含まれるソースファイルの関連情報をクリアすべき状況になった場合に発行されます。環境の属性の中に情報をキャッシュしておくような拡張機能ためのイベントです。

例えば、環境の中にすべてのモジュールのキャッシュが存在してる場合、ソースファイルが変更されると、ファイルからモジュール宣言から削除されてから、そのファイルに関するキャッシュのエントリーはクリアされます。

バージョン 0.5 で追加.

env-before-read-docs(app, env, docnames)

環境がすべての追加および変更されたファイルのリストを決定し、そのリストを読み込む直前に発行されるイベントです。拡張機能の作者は処理の直前にドキュメント名リストの順序を(インプレイスで)変更したり、Sphinxが変更を把握出来なかったドキュメント名を追加(ただし env.found_doc にないドキュメント名は決して追加しないでください)することができます。

イベントハンドラはドキュメント名をリストから削除することもできます; 注意深くこの方法を利用することで、Sphinxに変更済みのファイルを未変更であるとして扱わせることができます。

バージョン 1.3 で追加.

source-read(app, docname, source)

ソースファイルが読み込まれる時に発行されます。 source 引数はリストで、ひとつの要素はソースファイルのコンテンツを表します。コンテンツに関する処理を行ったり、要素に関してソースレベルでの変換を実装したりできます。

もしも、LaTeXと同じように、 $ 記号を、インラインの数式の区切り文字にしたい場合には、このイベントハンドラの中で、正規表現を使用して $...$:math:`...` に置き換えることで実現できます。

バージョン 0.5 で追加.

doctree-read(app, doctree)

doctreeがパースされ、環境から読み込まれ、pickle化される時に発行されます。 doctree をその場で変更できます。

missing-reference(app, env, node, contnode)

Pythonモジュールやオブジェクトへの相互参照が解決できないときに発行されます。もしも参照の問題を解決できる場合には、 node の代わりにドキュメントツリーに挿入される、新しいdocutilsのノードを返すことで、イベントハンドラ側で解決できます。通常このノードは、 contnode を子供として含む reference ノードです。

パラメータ
  • env -- ビルド環境 (app.builder.env)

  • node -- これから解決される pending_xref ノード。この属性は reftypereftargetmodnameclassname 属性であり、これらの属性によって、型と参照先ターゲットが決定されます。

  • contnode -- このノードは、将来の参照が持つ、テキストとフォーマット情報を持ちます。これは返される参照ノードの子供にならなければなりません。

バージョン 0.5 で追加.

doctree-resolved(app, doctree, docname)

環境がdoctreeに関して"resolved(解決)"と判断したときに発行されます。これは、すべての参照が解決され、目次が挿入された時、ということになります。 doctree はこのイベントハンドラ内で操作できます。

このイベントは、ライタークラスにビジターメソッドが存在しない、カスタムのノードを置換して処理するのに使用できます。もしもここで設定しない場合、未知のノードを見つけると、ライターはエラーを出しますが、設定することでエラーが出なくなります。

env-merge-info(app, env, docnames, other)

このイベントはドキュメントの並列読み込みが有効の場合にのみ発行されます。それぞれのサブプロセスがドキュメントを読み込んだ場合に一度だけ発行されます。

このイベントは拡張機能が特定の場所の環境中にデータを保存する場合に使用される必要があります。使用しないと、サブプロセス中で保存された情報をメインプロセスの環境内で利用できなくなります。

other はサブプロセス中での環境、env はメインプロセスでの環境です。docnames はこのサブプロセスにおいて読み込まれたドキュメント名のセットです。

このイベントの使用例については、 標準で提供されている sphinx.ext.todo を参照してください。この実装方法は env-purge-doc に似ています、ただし、情報が削除されるだけではなく、他の環境からの情報をメインプロセス環境に追加することができます。

バージョン 1.3 で追加.

env-updated(app, env)

ビルダーの update() メソッドの実行が完了し、環境とすべてのdoctreeが最新になった時に発行されます。

イベントハンドラより、ドキュメント名のイテレータを返すことができます。これらのドキュメントはアップデートされたとみなされ、書き込みフェイズにて新規書き込み(または書き換え)が行われます。

バージョン 0.5 で追加.

バージョン 1.3 で変更: イベントハンドラからの戻り値が利用されるようになりました。

env-check-consistency(app, env)

Emitted when Consistency checks phase. You can check consistency of metadata for whole of documents.

バージョン 1.6 で追加: As a experimental event

html-collect-pages(app)

HTMLビルダーが、ドキュメント以外のページの書き込みを開始するときに発行されます。 (pagename, context, templatename) という構成の要素を含むシーケンスを返すと、ページを追加できます。

バージョン 1.0 で追加.

html-page-context(app, pagename, templatename, context, doctree)

HTMLビルダーがコンテキストの辞書を作り、テンプレートを使用してレンダリングを行う時に発行されます。このイベントは、追加のカスタムの要素をコンテキストに追加する場合に使用できます。

pagename 引数はレンダリングされるページの、規範に則った名前です。規範というのは、 .html が付かず、パス区切りとしてスラッシュ(/)が使われている状態です。 templatename はレンダリングに使用するテンプレートの名前です。 reSTドキュメントのページのレンダリング時には、必ず 'page.html' となります。

context 引数はテンプレートエンジンがページをレンダリングする際に与えられる値の辞書になります。カスタムの値を持つように、変更することが可能です。キーは必ず文字列です。

doctree 引数はreSTドキュメントから作成する場合にはdoctreeとなります。もしもHTMLテンプレートからのみ作成されるページの場合には、 None となります。

イベントハンドラは文字列を返すことができます、この文字列は 'page.html' に代わりHTMLテンプレートとして、このページのレンダリングに利用されるテンプレート名になります。

バージョン 0.4 で追加.

バージョン 1.3 で変更: 戻り値により使用するテンプレート名を指定できるようになりました。

build-finished(app, exception)

ビルドが完了し、Sphinxが終了する際に発行されます。通常はクリーンアップに使用されます。このイベントは、ビルドプロセスが例外を上げたときにも発行されます。その場合には、 exception 引数が渡されます。アプリケーションの中で発生した例外は、このイベントハンドラが終了した段階で、再度投げられます。もしもビルドプロセスが例外を発生しなかった場合には、 exceptionNone になります。これによって、例外の種類ごとの、クリーンアップの処理をカスタム化できます。

バージョン 0.5 で追加.

Sphinx のバージョン確認

作製した拡張をSphinxのAPI変更に追従させる為、この仕組みを使用してください。

sphinx.version_info = (3, 0, 0, 'beta', 0)

プログラムから扱いやすい形式の Sphinx バージョンです。

バージョン情報は 5要素のタプルで表現されます。バージョン 1.2.1 beta 3 では (1, 2, 1, 'beta', 3) と表現されます。4番目の要素は alphabetarcfinal のいずれかの値を取ります。 final の場合、最後の要素は常に 0 となります。

バージョン 1.2 で追加: バージョン1.2より前では sphinx.__version__ (文字列) を参照してください。

Config オブジェクト

class sphinx.config.Config(config={}, overrides={})[ソース]

ビルド設定ファイルを抽象化したオブジェクトです。

config オブジェクトはすべての設定値を属性として利用できるよう保持します。

It is exposed via the sphinx.application.Application.config and sphinx.environment.Environment.config attributes. For example, to get the value of language, use either app.config.language or env.config.language.

テンプレートブリッジ

class sphinx.application.TemplateBridge[ソース]

このクラスは、"テンプレートへのブリッジ"を定義しています。テンプレートブリッジというのは、与えられたテンプレート名と、コンテキストを利用して、テンプレートをレンダリングするクラスのことです。

init(builder, theme=None, dirs=None)[ソース]

テンプレートのシステムの初期化を行うために、ビルダーから呼ばれます。

builder はビルダーオブジェクトで、 builder.config.templates_path の値を使用することになるでしょう。

themesphinx.theming.Theme オブジェクト、あるいは None になります。後者の場合には、 dirs に固定ディレクトリのパスが入ったリストが渡され、この中からテンプレートを探します。

newest_template_mtime()[ソース]

このメソッドはビルダーから呼ばれます。テンプレートが変更されたことで、出力ファイルを再レンダリングする必要があるかどうかの判断をするために使用されます。変更された、最新のテンプレートのmtimeを返します。デフォルトの実装では 0 を返します。

render(template, context)[ソース]

指定された context (Python辞書)を使用して、 template で指定されたファイル名のテンプレートのレンダリングを行います。ビルダーから呼ばれます。

render_string(template, context)[ソース]

指定された context (Python辞書)を使用して、 template で指定された文字列形式のテンプレートのレンダリングを行います。ビルダーから呼ばれます。

例外

exception sphinx.errors.SphinxError[ソース]

Base class for Sphinx errors.

これは "ナイスな" 例外を作成するための基底クラスです。この例外が発生すると、Sphinxはビルドを中止し、例外のカテゴリとメッセージをユーザーに表示します。

拡張プログラムでは、この例外を継承しカスタマイズすることが強く推奨されます。

SphinxError から 継承されない 例外は予期しない例外として扱われ、トレースバックの一部を表示(そして、全部を一時ファイルに保存)します。

category

例外の "category" の記述部分は、例外内容を文字列に変換する場合に利用されます("category: message" という書式)。 例外のサブクラスに応じて適切に設定するべきです。

exception sphinx.errors.ConfigError[ソース]

Configuration error.

exception sphinx.errors.ExtensionError(message, orig_exc=None)[ソース]

Extension error.

exception sphinx.errors.ThemeError[ソース]

Theme error.

exception sphinx.errors.VersionRequirementError[ソース]

Incompatible Sphinx version error.