追加のマークアップ構成

Sphinxは,多くの新しいディレクティブと解釈されたテキストの役割を標準のreStructuredTextマークアップに追加します.このセクションには,これらの機能の参照資料が含まれています. Pythonのドキュメントで使用されていますが,「標準」のreStructuredTextコンストラクトのドキュメントはここには含まれていません.

注釈

これは,Sphinxの拡張マークアップ機能の概要です.機能全体の範囲は,Sphinxのドキュメント<http://sphinx.pocoo.org/contents.html>` _にあります.

メタ情報のマークアップ

sectionauthor

現在のセクションの作成者を識別します.引数には,プレゼンテーションに使用できる(ただしそうではない)作成者の名前と電子メールアドレスを含める必要があります.アドレスのドメイン名部分は小文字にする必要があります.例:

.. sectionauthor:: Guido van Rossum <guido@python.org>

現在,このマークアップは出力には一切反映されていませんが,貢献していただいた箇所を追跡するのに役立ちます.

モジュール固有のマークアップ

このセクションで説明するマークアップは,文書化されているモジュールに関する情報を提供するために使用されます.各モジュールは,そのモジュールのファイルに文書化する必要があります.通常,このマークアップはそのファイルのタイトルヘッダーの後に表示されます.典型的なファイルは次のように始まります:

:mod:`parrot` -- Dead parrot access
===================================

.. module:: parrot
   :platform: Unix, Windows
   :synopsis: Analyze and reanimate dead parrots.
.. moduleauthor:: Eric Cleese <eric@python.invalid>
.. moduleauthor:: John Idle <john@python.invalid>

ご覧のとおり,モジュール固有のマークアップは,2つのディレクティブ,「module」ディレクティブと「moduleauthor」ディレクティブで構成されています.

module

このディレクティブは,モジュール(またはパッケージサブモジュール,この場合,パッケージ名を含む名前を完全修飾する必要があります)の説明の開始をマークします.

`` platform``オプションは,存在する場合,モジュールが利用可能なプラットフォームのコンマ区切りリストです(すべてのプラットフォームで利用可能な場合,本オプションは省略したほうがよいです).キーは短い識別子です.使用されている例には,「IRIX」,「Mac」,「Windows」,および「Unix」が含まれます.該当する場合は,すでに使用されているキーを使用することが重要です.

`` synopsis``オプションは,モジュールの目的を説明する1つの文で構成する必要があります-現在,Global Module Indexでのみ使用されています.

deprecated オプションは,モジュールをdeprecatedとマークするために(値のない)指定をすることができます.各場所で指定されます.

moduleauthor

moduleauthor 命令は複数回現れることがあり, sectionauthor が(複数の)文書の作者を指定するのと同じように,モジュールコードの作者を指定します.この場合も,現在は何も出力されません.

注釈

モジュール記述ファイルのセクションタイトルは,概要ファイルの目次ツリーに挿入されるため,意味のあるものにすることが重要です.

情報単位

モジュールが提供する特定の機能を記述するために使用される多くのディレクティブがあります.各ディレクティブでは,記述されている内容に関する基本情報を提供するために1つ以上の記号が必要であり,その内容は記述である必要があります.基本バージョンでは,一般インデックスにエントリが作成されます.インデックスエントリが必要ない場合は,ディレクティブオプションフラグ :noindex: を指定できます.次の例は,このディレクティブタイプのすべての機能を示しています.

.. function:: spam(eggs)
              ham(eggs)
   :noindex:

   Spam or ham the foo.

オブジェクトメソッドまたはデータ属性の記号には,それらがどのタイプに属しているかがコンテキストから明らかな場合でも,常に型名(.. method:: FileInput.input(...))を含める必要があります.これにより,一貫した相互参照が可能になります. "context managers" などの抽象プロトコルに属するメソッドを記述する場合は,(擬似)タイプ名も含めて,インデックスエントリの情報量を増やします.

ディレクティブは次のとおりです.

cpp:function

C++関数について説明します.記号は次のようにC++で与えられるべきです.

.. cpp:function:: bgeot::simplex_structure(dim_type d)
c:function

C関数について説明します.記名は次のようにCで与えられるべきです.

.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

関数型プリプロセッサマクロの記述にも使用されます.引数の名前は,説明で使用できるように指定する必要があります.

シグネチャはreSTインラインで解析されないため,バックスラッシュでエスケープするアスタリスクは必要ありません.

cmember

C構造体メンバについて説明します.記名の例

.. cmember:: PyObject* PyTypeObject.tp_bases

説明のテキストには,許可される値の範囲,値の解釈方法,および値を変更できるかどうかを含める必要があります.構造体のメンバをテキストで参照する場合は, member ロールを使用する必要があります.

cmacro

"simple" Cマクロについて説明します.単純なマクロは,コードの展開に使用されるマクロですが,引数を取らないため関数として記述できません.これは,単純な定数の定義には使用できません.Pythonマニュアルでの使用例には, PyObject_HEADPy_BEGIN_ALLOW_THREADS などがあります.

ctype

Cの型を記述します.記名は型名だけでなければなりません.

cvar

グローバルC変数を記述します.記名には,次のような種類を含める必要があります.

.. cvar:: PyObject* PyClass_Type
data

"定義された定数" クラスおよびオブジェクト属性として使用される変数と値を含む,モジュール内のグローバルデータについては,この環境での説明はありません.

exception

例外クラスについて説明します.署名には,コンストラクタ引数とともに括弧を含めることができますが,必ずしも含める必要はありません.

function

モジュールレベルの関数について説明します.署名には,オプションのパラメータを括弧で囲んだパラメータを含める必要があります.わかりやすくするために,デフォルト値を指定できます.次に例を示します.

.. function:: Timer.repeat([repeat=3[, number=1000000]])

このディレクティブを使用したオブジェクトメソッドの説明はありません.モジュールの公開インタフェースの一部としてモジュール名前空間に配置されたバウンドオブジェクトメソッドは,ほとんどの目的で通常の関数と同等であるため,これを使用して記述されます.

説明には,必要なパラメータとその使用方法(特に,パラメータとして渡された可変オブジェクトが変更されたかどうか),副作用,および考えられる例外に関する情報を含める必要があります.簡単な例を挙げることができます.

class

クラスを記述します.記名には,コンストラクター引数として表示されるパラメーターを持つ括弧を含めることができます.

attribute

オブジェクトデータ属性について説明します.記述には,予想されるデータの種類及びそれを直接変更できるかどうかに関する情報を含めます.

method

オブジェクトメソッドについて説明します.パラメータには self パラメータを含めないでください.説明には, function の説明と同様の情報を含める必要があります.

opcode

Pythonの bytecode 命令について説明します.

cmdoption

コマンドラインオプションまたはスイッチについて説明します.オプションの引数名は山括弧で囲む必要があります.例

.. cmdoption:: -m <module>

   Run a module as a script.
envvar

Pythonが使用または定義する環境変数について説明します.

次のディレクティブの汎用バージョンもあります.

describe

このディレクティブは,前述の特定の書式設定と同じ書式設定を生成しますが,索引エントリや相互参照ターゲットは作成しません.たとえば,このドキュメントのディレクティブを記述するために使用されます.例えば

.. describe:: opcode

   Describes a Python bytecode instruction.

コード例の表示

Pythonソースコードや対話型セッションの例は,標準的なreSTリテラルブロックを使って表現されます.それらは,前の段落の終わりにある :: で始まり,インデントで区切られます.

対話型のセッションを表現するには,プロンプトと出力をPythonコードとともに含める必要があります.対話型のセッションでは,特別なマークアップは必要ありません.入力または出力の最後の行が表示された後は, "未使用" プライマリプロンプトは表示されません.これは, しない ことの例です.

>>> 1 + 1
2
>>>

構文の強調表示は,次のようなスマートな方法で処理されます.

  • ソースファイルごとに "highlighting language" があります.デフォルトでは,ほとんどのファイルでPythonスニペットをハイライトする必要があるため,これは 'python' です.

  • Pythonのハイライトモードでは,インタラクティブセッションが自動的に認識され,適切にハイライト表示されます.

  • ハイライト表示の言語は,次のように highlightlang ディレクティブを使用して変更できます.

    .. highlight:: c
    

    この言語は,次の highlight ディレクティブが検出されるまで使用されます.

  • 強調表示言語に通常使用される値は次のとおりです.

    • python (デフォルト)

    • c

    • rest

    • none (ハイライトなし)

  • 現在の言語でのハイライト表示に失敗した場合,ブロックはハイライト表示されません.

プレーンテキストのみを含む外部ファイルにサンプルテキストを保存することで,より長い逐語的テキストの表示を含めることができます.ファイルは literalinclude 指令を使用して含めることができる. 1 たとえば,Pythonソースファイル example.py を含めるには,次のように指定します.

.. literalinclude:: example.py

ファイル名は,現在のファイルのパスからの相対パスです.ドキュメント固有のインクルードファイルは, Doc/includes サブディレクトリに置く必要があります.

インラインマークアップ

前述したように,Sphinxはインタープリターされたテキストロールを使用して,文書にセマンティックmarkupを挿入します.

関数/メソッド引数のようなローカル変数の名前は例外であり,単純に *var* と印をつけるべきです.

他の全てのロールについては, :rolename:`content` と書かなければなりません.

クロスリファレンスの役割をより汎用的にする機能がいくつか追加されています.

  • reSTダイレクトハイパーリンクのように,タイトルと参照先を明示的に指定できます. :role:`title <target>`target を参照しますが,リンクテキストは title になります.

  • コンテンツの先頭に ! を付けると,参照やハイパーリンクは作成されません.

  • Pythonオブジェクトロールの場合,コンテンツの先頭に ~` を付けると,リンクテキストはターゲットの最後のコンポーネントになります.たとえば, ``:meth:`~Queue.Queue.get`Queue.Queue.get を参照しますが, get だけをリンクテキストとして表示します.

    HTML出力では,リンクの title 属性(マウスをかざすとツールチップとして表示される)は常に完全なターゲット名となります.

次のロールはモジュール内のオブジェクトを参照し,一致する識別子が見つかった場合はハイパーリンクが設定されることがあります.

mod

モジュールの名前.ドット名を使用できます.パッケージ名にも使用してください.

func

Python関数の名前.ドット名を使用できます.読みやすさを向上させるために,ロールテキストに末尾の括弧を含めないでください.識別子を検索するときに括弧が取り除かれます.

data

モジュールレベルの変数または定数の名前です.

const

"定義済み" 定数の名前.これは,C言語の #define または変更を意図していないPython変数である可能性があります.

class

クラス名.ドット名を使用できます.

meth

オブジェクトのメソッドの名前.ロールテキストには,タイプ名とメソッド名を含める必要があります.ドット名を使用できます.

attr

オブジェクトのデータ属性の名前.

exc

例外の名前.ドット名を使用できます.

このmarkupで囲まれた名前には,モジュール名やクラス名を含めることができます.たとえば, :func:`filter` は,現在のモジュールの filter という名前の関数,またはその名前の組み込み関数を参照することができます.対照的に,:func:`foo.filter`foo モジュールの filter 機能を明確に指しています.

通常,これらの役割の名前は,最初に修飾子なしで検索され,次に現在のモジュール名が追加され,次に現在のモジュールとクラス名(存在する場合)が追加されます.名前の前にドットを付けると,この順序は逆になります.たとえば, codecs モジュールのドキュメントでは, :func:`open```は常に組み込み関数を指し, ``:func:`.open`codecs.open を指しています.

同様のヒューリスティックを使用して,名前が現在文書化されているクラスの属性であるかどうかを判別します.

次の役割は,APIドキュメントで定義されている場合,C言語構文への相互参照を作成します.

cdata

C言語変数の名前.

cfunc

C言語関数の名前.末尾にカッコを含める必要があります.

cmacro

上で定義した "単純な" Cマクロの名前.

ctype

C言語型の名前.

次の役割は相互参照を作成する可能性がありますが,オブジェクトを参照しません.

token

文法トークンの名前(リファレンスマニュアルで,プロダクションディスプレイ間のリンクを作成するために使用されます).

次の役割は,用語集内の用語への相互参照を作成することです.

term

用語集内の用語への参照.用語集は,用語と定義の定義リストを含む glossary ディレクティブを使用して作成されます. term markupと同じファイルにある必要はありません.実際,Pythonドキュメントの glossary.rst ファイルには,デフォルトでグローバルな用語集が1つあります.

用語集で説明されていない用語を使用すると,ビルド中に警告が表示されます.


次のロールは,テキストを別のスタイルで書式設定する以外は特に何も行いません.

command

rm などのOSレベルのコマンドの名前.

dfn

テキスト内の用語の定義インスタンスをマークします.(索引項目は生成されません.)

envvar

環境変数.索引項目が生成されます.

file

ファイルまたはディレクトリの名前.コンテンツ内では,次のように中括弧を使用して "変数" 部分を示すことができます.

... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...

ビルドされたドキュメントでは, x はPythonのマイナーバージョンに置き換えられるため,異なる表示になります.

guilabel

対話型ユーザーインターフェイスの一部として表示されるラベルは, guilabel を使用してマークする必要があります.これには, curses やその他のテキストベースのライブラリを使用して作成されたテキストベースのインターフェイスのラベルも含まれます.インタフェースで使用されるラベルには,ボタン・ラベル,ウィンドウ・タイトル,フィールド名,メニューおよびメニュー選択名,選択リスト内の値など,このロールを付ける必要があります.

kbd

一連のキーストロークをマークします.キーシーケンスの形式は,プラットフォームまたはアプリケーション固有の規則によって異なります.関連する規則がない場合は,修飾キーの名前を記述して,新しいユーザーやネイティブでないユーザーがアクセスしやすいようにする必要があります.例えば, xemacs キーシーケンスが :kbd:`C-x C-f` のようにマークされるかもしれませんが,特定のアプリケーションやプラットフォームを参照せずに,同じシーケンスが :kbd:`Control-x Control-f` としてマークされるべきです.

keyword

Pythonのキーワードの名前.

mailheader

RFC822形式のメールヘッダーの名前.このmarkupは,ヘッダーが電子メールメッセージで使用されていることを意味するのではなく,同じ "スタイル" の任意のヘッダーを参照するために使用できます.これは,さまざまなMIME仕様によって定義されたヘッダーにも使用されます.ヘッダ名は,実際に見られるのと同じ方法で入力されるべきであり,2つ以上の一般的な用法がある場合には,camel-casing規約が好ましいです.例 :mailheader:`Content-Type`

makevar

make 変数の名前.

manpage

例えば :manpage:`ls(1)` といったセクションを含むUnixマニュアルページへの参照です.

menuselection

メニューの選択には menuselection の役割を使って印を付けます.これは,サブメニューの選択および特定の操作の選択を含む,メニュー選択の完全なシーケンス,またはそのようなシーケンスの任意のサブシーケンスをマークするために使用されます.個々の選択項目の名前は --> で区切る必要があります.

たとえば,選択範囲 "Start > Programs" をマークするには,次のmarkupを使用します.

:menuselection:`Start --> Programs`

一部のオペレーティングシステムでコマンドがダイアログを開くことを示すために使用される省略記号など,末尾のインジケータを含む選択を含める場合は,選択名からインジケータを省略する必要があります.

mimetype

MIMEタイプの名前,またはMIMEタイプのコンポーネント(単独でとられる大部分または小部分).

newsgroup

Usenet newsgroupの名前.

option

実行可能プログラムのコマンドラインオプションです.先頭の(複数の)ハイフンを含める必要があります.

program

実行可能プログラムの名前.これは,一部のプラットフォームの実行可能ファイルのファイル名とは異なる場合があります.特に, .exe (その他)拡張子はWindowsプログラムでは省略されるべきです.

regexp

正規表現.引用符は含めないでください.

samp

コードなどのリテラルテキスト. :file: のように,コンテンツ内で中括弧を使用して "variable" 部分を示すことができます.

"可変部" 表示が必要ない場合は,代わりに標準の ``code`` を使用してください.

var

PythonまたはCの変数またはパラメータ名.

次の役割は外部リンクを生成します.

pep

Python Enhancement Proposalへの参照.これにより,適切なインデックスエントリが生成されます.テキスト "PEP number" が生成されます.HTML出力では,このテキストは指定されたPEPのオンラインコピーへのハイパーリンクです.

rfc

Internet Request for Commentsへの参照.これにより,適切なインデックスエントリが生成されます.テキスト "RFC number" が生成されます.HTML出力では,このテキストは指定されたRFCのオンラインコピーへのハイパーリンクです.

標準のreST markupを使用できるため,ハイパーリンクを含めるための特別な役割はありません.

クロスリンクマークアップ

ドキュメント内の任意のセクションへの相互参照をサポートするために,標準のreSTラベルは少し "abused" されます.各ラベルはセクションタイトルの前に置く必要があります.すべてのラベル名は,ドキュメントソース全体で一意である必要があります.

これらのセクションを参照するには, :ref:`label-name` ロールを使用します.

.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

:ref: 呼び出しはセクションタイトルに置き換えられる.

段落レベルのmarkup

これらのディレクティブは短い段落を作成し,通常のテキストと同様に情報単位内で使用できます.

note

APIに関する特に重要な情報で,注意事項が関連するAPIのあらゆる部分を使用する際にユーザーが注意する必要があります.指示の内容は完全な文章で書かれ,すべての適切な句読点を含むべきである.

.. note::

   This function is not suitable for sending spam e-mails.
warning

APIに関する重要な情報であり,警告が関連するAPIのどの部分を使用する場合でも,ユーザは十分に注意する必要があります.指示の内容は完全な文章で書かれ,すべての適切な句読点を含むべきである.これは,セキュリティに関する情報のために note よりも推奨されるという点で note とは異なります.

versionadded

このディレクティブは,記述された機能をライブラリまたはC APIに追加したPythonのバージョンを記述します.これがモジュール全体に適用される場合は,モジュールセクションの先頭の散文の前に配置する必要があります.

最初の引数は指定する必要があり,問題のバージョンです.変更の*簡単な*説明で構成される2番目の引数を追加できます.

.. versionadded:: 2.5
   The *spam* parameter.

指示記号と説明の間に空白行があってはならないことに注意してください.これは,markup内でこれらのブロックを視覚的に連続させるためです.

versionchanged

versionadded と似ていますが,名前の付いた機能でいつ何が変更されたかを何らかの方法で記述します(新しいパラメータ,変更された副作用など.).


seealso

多くのセクションには,モジュールドキュメントまたは外部ドキュメントへの参照のリストが含まれています.これらのリストは seealso ディレクティブを使用して作成されます.

seealso ディレクティブは通常,サブセクションの直前のセクションに配置されます.HTML出力の場合は,テキストのメインフローから枠で囲んで表示されます.

seealso ディレクティブの内容はreST定義リストでなければなりません.例

.. seealso::

   Module :mod:`zipfile`
      Documentation of the :mod:`zipfile` standard module.

   `GNU tar manual, Basic Tar Format <http://link>`_
      Documentation for tar archive files, including GNU tar extensions.
rubric

このディレクティブは,目次ノードの作成に使用されない段落見出しを作成します.現在は "脚注" キャプションに使用されています.

centered

この指示は,中央に太字の段落を作成します.次のように使用します.

.. centered::

   Paragraph contents.

目次markup

reSTには複数の文書を相互接続したり,文書を複数の出力ファイルに分割したりする機能がないため,Sphinxではカスタム・ディレクティブを使用して,文書を構成する単一のファイルと目次の間に関係を追加します. toctree の指示は中心的な要素です.

toctree

このディレクティブは,ディレクティブ本体で指定されたファイルの個々のTOC( "sub-TOC trees" を含む)を使用して,現在の場所に "TOC tree" を挿入します.ツリーの深さを示すために,数値の maxdepth オプションを指定することができます.デフォルトでは,すべてのレベルが含まれます.

(ライブラリ参照インデックスから取得された)次の例を考えてみます

.. toctree::
   :maxdepth: 2

   intro.rst
   strings.rst
   datatypes.rst
   numeric.rst
   (many more files listed here)

これにより,次の2つのことが実現します.

  • これらすべてのファイルの目次が挿入されます.最大深さは2で,1つの見出しがネストされます.ファイル内の toctree ディレクティブも考慮されます.

  • Sphinxはファイル intro.rststrings.rst などの相対的な順序を知っており,それらが表示されているファイル,つまりライブラリーインデックスの子であることを知っています.この情報から "next chapter" , "previous chapter" , "parent chapter" リンクが生成されます.

最終的に,構築プロセスに含まれる全てのファイルは,一つの toctree ディレクティブ内になければなりません.含まれていないファイルが見つかった場合,Sphinxは警告を発します.

ソースディレクトリのルートにある特殊ファイル contents.rst は,TOCツリー階層の "root" です. "Contents" ページが生成されます.

索引生成markup

Sphinxは,前述のように,すべての情報単位(関数,クラス,属性など)から索引項目を自動的に作成します.

しかし,索引をより包括的にし,言語参照などの情報単位に情報が主に含まれていない文書の索引項目を有効にするための明示的な指示もあります.

ディレクティブは index で,1つ以上のインデックスエントリを含みます.各エントリは,コロンで区切られた型と値で構成されます.

.. index::
   single: execution; context
   module: __main__
   module: sys
   triple: module; search; path

このディレクティブには5つのエントリが含まれています.これらのエントリは,生成されたインデックス内のエントリに変換され,インデックスステートメントの正確な場所にリンクされます(オフラインメディアの場合は,対応するページ番号).

可能なエントリタイプは次のとおりです.

single

単一の索引項目を作成します.サブエントリを作成するには,サブエントリのテキストをセミコロン(以下では,この表記法を使用して,どの項目が作成されるかを説明します.)で区切ります.

pair

pair: loop; statement は, loop; statementstatement; loop の2つのインデックスエントリを作成するショートカットです.

triple

同様に, triple: module; search; path は, module; search pathsearch; path, modulepath; module search の3つのインデックスエントリを作成するショートカットです.

モジュール,キーワード,演算子,オブジェクト,例外,ステートメント,組み込み

これらはすべて,2つのインデックスエントリを作成します.たとえば, module: hashlib はエントリ module; hashlibhashlib; module を作成します.

"single" エントリのみを含むインデックスディレクティブには,次のような短縮表記があります.

.. index:: BNF, grammar, syntax, notation

これにより,4つの索引項目が作成されます.

文法作成画面

形式文法の生成を表示するために,特別なマークアップを使用できます.このマークアップは単純であり,BNF(または派生した形式)のすべての側面をモデル化しようとするものではありませんが,シンボルの使用をシンボルの定義へのハイパーリンクとして表示するような方法で,コンテキストフリーの文法を表示するのに十分なものです.次の指示があります.

productionlist

このディレクティブは,プロダクションのグループを囲むために使用します.各プロダクションは1行で指定され,次の定義からコロンで区切られた名前で構成されます.定義が複数行にまたがる場合,各継続行は最初の行と同じ列に配置されたコロンで始まる必要があります.

空行は productionlist ディレクティブ引数内では使用できません.

定義には,解釈済みテキストとしてマークされたトークン名(例 unaryneg ::= "-" `integer` )を含めることができます.これにより,これらのトークンの生成への相互参照が生成されます.

本番環境ではそれ以上のreST解析は行われないので, *| 文字を回避する必要はありません.

以下は,Python Reference Manualから引用した例です.

.. productionlist::
   try_stmt: try1_stmt | try2_stmt
   try1_stmt: "try" ":" `suite`
            : ("except" [`expression` ["," `target`]] ":" `suite`)+
            : ["else" ":" `suite`]
            : ["finally" ":" `suite`]
   try2_stmt: "try" ":" `suite`
            : "finally" ":" `suite`

置換

マニュアルシステムには,デフォルトで定義されている3つの代替があります.これらはビルド設定ファイル conf.py に設定されます.

|release|

このドキュメントで言及されているPythonリリースに置き換えられました.これはalpha/beta/release候補タグを含む完全なバージョン文字列で,例えば 2.5.2b3 のようになります.

|version|

マニュアルに記載されているPythonバージョンに置き換えられました.これは,バージョン 2.5.1 でも 2.5 のようにメジャーバージョンとマイナーバージョンの部分だけで構成されています.

|today|

今日の日付,または構築構成ファイルで設定された日付で置き換えられます.通常は April 14, 2007 というフォーマットです.

脚注

1

標準の .. include ディレクティブがありますが,ファイルが見つからないとエラーが発生します.これは警告のみを発します.