その他のマークアップ

ファイルに関するメタデータ

reSTには “フィールドリスト”という考えがあります。以下のようなものが、このフィールドのマークアップのリストのサンプルになります:

:fieldname: Field content

docutilsは、ファイルの先頭付近のフィールドリストを “docinfo” としてパースします。これは通常のドキュメントでは著者名や、公開日などのメタデータを記録するのに使用されます。 Sphinxでは, docinfoはメタデータとして使用されますが、出力はされません。フィールドリストは、ドキュメントのタイトルの後に、いつものように表示されます。

このタイミングでは、以下のメタデータのフィールドが識別されています:

tocdepth

このファイルに表示する目次の最大の深さ

バージョン 0.4 で追加.

nocomments

もし設定されていれば、このソースファイルから生成されたページをウェブアプリケーションが表示する際には、コメントフォームが表示されなくなります。

orphan

もしこれが設定されると、toctreeから参照されていない時に出力される警告が抑制されます。

バージョン 1.0 で追加.

メタ情報マークアップ

.. sectionauthor:: name <email>

現在のセクションの著者名を指定します。引数には必ず、表示するための著者の名前と、電子メールのアドレスを入れます。アドレスのドメイン名の部分は小文字でなければなりません。 サンプル:

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

デフォルトでは、このマークアップは出力に反映されません(貢献者の名前を調べる手助けにはなります)。しかし、設定ファイルの show_authorsTrue に設定すると、出力ファイルの中にこの情報に関する段落が作成されます。

.. codeauthor:: name <email>

codeauthor ディレクティブは、 sectionauthor の名前と同じく、説明しているコードの作者名について、複数人書くことができます。 show_authors 設定値を True にしないかぎり、出力はされません。

インデックス生成のためのマークアップ

Sphinxはすべてのオブジェクトの説明(関数、クラス、属性)から、自動的にインデックスのエントリーを作成します。オブジェクトの説明に関しては、 Sphinxドメイン で詳しく説明しています。

しかし、これ以外に明示的に指定するディレクティブもあります。これを使用することで、言語のリファレンスのように、メインの情報のユニットが存在しない情報をドキュメントの中に書いてインデックスのエントリーを作ることができるようになります。より包括的なインデックスを作成できるようになります。

.. index:: <entries>

このディレクティブは一つ以上のインデックスのエントリーを含みます。それぞれのエントリーはコロン(:)で区切られた、タイプ、値を含みます。

例えば:

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

The execution context
---------------------

...

このディレクティブは5つのエントリーを含んでいます。これらは生成されたインデックスのエントリーに変換され、index文の正確な位置へのリンクが張られることになります。オフラインのメディアに出力される場合には、リンクの代わりに対応するページ番号が出力されます。

indexディレクティブはそのソースの位置のターゲットとのクロスリファレンスを生成するため、それらが参照するものの 前の位置 に置くことが大切になります。上記のサンプルコードの例では、リンクを張りたい見出しの前に配置されています。

設定可能なエントリーのタイプは以下の通りです:

single

単体のインデックスのエントリーを作成します。 サブエントリーのテキストとの間をセミコロンで区切ることにより、サブエントリーを作ることもできます。この記法はどのエントリーが作成されたのか、という説明のところで詳しく説明します。

pair

pair: loop; statement はインデックスエントリーを2つ作成します。 loop; statementstatement; loop の2つのエントリーが作成されます。

triple

pairと似ていますが triple: module; search; path は3つのエントリーを作成します。 module; search path, search; path, module, path; module search が作成されます。

see

see: entry; other という項目があると、 entry から other を参照するインデックスエントリーが作成されます。

seealso

see と似ていますが、 “see” の代わりに、 “see also” を挿入します。

module, keyword, operator, object, exception, statement, builtin

これらはすべて、2つのエントリーを作成します。例えば、 module: hashlib という項目があると、 module; hashlibhashlib; module の2つのエントリーが作成されます。(これらはPython固有で、deperecatedになっています。)

もしエクスクラメーションマーク(!)を前に付けると、主要なインデックスエントリーである、ということを表現できます。主要なインデックスは、生成されたインデックスの中で強調されます。例えば、2つのページが次のようなディレクティブを持っていたとします:

.. index:: Python

そして、次の内容を含むページがあったとします:

.. index:: ! Python

この場合、最後のページへのバックリンクが3つの中では強調されて表示されます。

“single”のエントリーだけが含まれるindexディレクティブの場合、以下のように短縮記法で簡単に作成することもできます:

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

これは4つのインデックスのエントリーが作成されます。

バージョン 1.1 で変更: seeseealso を追加しました。

:index:

index ディレクティブは、ブロックレベルのマークアップで、次のパラグラフの先頭に対するリンクを生成します。これとは別に、直接リンクターゲットに設定するロールもあります。

ロールのコンテンツは、文章の中にあるシンプルなフレーズで、そのままインデックスのエントリーとして使用されます。テキストと入力エントリーの組み合わせになっていて、明示的なクロスリファレンスのターゲットになります。この場合、ターゲットの部分は上記で説明したディレクティブの機能をフルに使うことができます:

This is a normal reST :index:`paragraph` that contains several
:index:`index entries <pair: index; entry>`.

バージョン 1.1 で追加.

タグを使用したインクルード

.. only:: <expression>

が真のときだけ、ディレクティブの内容をインクルードします。式は以下のようにタグで構成されます。

.. only:: html and draft

未定義のタグはfalseになります。定義されたタグ(コマンドラインの -t オプションもしくは conf.py で設定: here を参照)はtrueとして扱われます。カッコも含めて、ブール演算も使用できます。真偽値の組み合わせとカッコ(html and (latex or draft) というような表現)がサポートされています。

現在のビルダー (htmllatextext) の フォーマット名前 が常にタグ [1] として設定されます。フォーマットと名前とを明示的に区別するために、 format_builder_ というプレフィックスも追加されました。 例: epubビルダーは htmlepubformat_htmlbuilder_epub の4つのタグが定義されます。

これらの標準タグは、conf.pyを読み込んだ に設定されるため、conf.pyではこれらのタグの有無を参照できません。

タグは`識別子 (identifier) およびキーワード (keyword) <https://docs.python.org/3/reference/lexical_analysis.html#identifiers>`_ で規定された Python の標準的な識別子の文法に従わなければなりません。言い換えると、タグの表現は Python の変数の文法に準拠したもののみが許されます。ASCII文字に限れば、A から Z までの大文字、小文字、アンダースコア _、そして先頭以外での 0 から 9 までの数字から構成されるものになります。

バージョン 0.6 で追加.

バージョン 1.2 で変更: builder名とプレフィックスが追加されました。

テーブル

標準のreStructuredTextの表 を使用すると、HTML出力では非常にきれいな表を作成できますが、LaTeXで出力すると、ちょっとがっかりしてしまうでしょう。現在の仕様ではカラムを自動で正しく決定するのは簡単ではありません。このような理由から、それをサポートするディレクティブがいくつか用意されています:

.. tabularcolumns:: column spec

このディレクティブは次に作成するテーブルの “カラム仕様” を設定します。仕様はSphinxがテーブルの変換に使用している、LaTeXの tabulary パッケージ環境のためのものです。2番目の引数として設定します。以下のような値を設定します:

|l|l|l|

これは、3つの左寄せの、改行なしのカラムの意味になります。それぞれのカラムで、長いテキストを適切に自動的に改行させるためには、標準の p{width} 構造体を使用するか、tabularyの自動設定を使用します。

L

左寄せのカラム。長さは自動調整。

R

右寄せのカラム。長さは自動調整。

C

中央寄せのカラム。長さは自動調整。

J

テキストを広げるカラム。長さは自動調整。

The automatic widths of the LRCJ columns are attributed by tabulary in proportion to the observed shares in a first pass where the table cells are rendered at their natural “horizontal” widths.

デフォルトでは、Sphinxはすべてのカラムに対して L を適用したレイアウトを自動で行います。

ヒント

For columns which are known to be much narrower than the others it is recommended to use the lowercase specifiers. For more information, check the tabulary manual.

バージョン 0.3 で追加.

警告

Tables with more than 30 rows are rendered using longtable, not tabulary, in order to allow pagebreaks.

オブジェクトの説明などのリストのような要素や、ブロッククオート、リストなどを含むテーブルは、 tabulary 環境では、箱に並べることはできません。tabularcolumns ディレクティブを与えていない場合は、LaTeX標準の tabular 環境が使用されます。このような要素を含めようとしている場合、テーブルに tabulary がセットされますが、これらの要素ほ含むカラムには、 p{width} コンストラクタを使うようにしてください。

Literal blocks do not work with tabulary at all, so tables containing a literal block are always set with tabular. Also, the verbatim environment used for literal blocks only works in p{width} columns, which means that by default, Sphinx generates such column specs for such tables.

脚注

[1]

ほとんどのビルダーでは名前とフォーマットは同じです。現時点ではhtmlビルダーから派生したビルダーだけがビルダーのフォーマットと名前とを区別するために違う値が設定されています。

現在のビルダーのtagはビルダーの初期化後に確定するため、 conf.py では提供されないことに注意して下さい。