インラインマークアップ

Sphinxは解釈済みのテキストのロールというものを使用して、用語の意味を記述して、リンクを張ったりすることができます。これを記述する時は :ロール名:`内容` というフォーマットで記述します。

ノート

デフォルトのロール(`content`)には標準では特別な意味を持っていません。必要に応じてどのように使用してもかまいません。例えば変数名として使用する、などです。 default_role という設定値を変更することで、デフォルトのロールに対して、既存のロールを設定することができます。

クロスリファレンス文法

クロスリファレンスは、意味解釈済みのテキストロールから生成されます。基本的には :ロール:`用語` という形式で書くだけでクロスリファレンスを作成することができます。このときは 用語 というアイテム名で、 ロール で指定されたタイプを持つリンクが作成されます。リンクに表示されるテキストは 用語 と同じになります。

追加の補助機能がいくつかありますが、これはロールに対するクロスリファレンスの目的を増やすものになります。:

• :ロール:`タイトル <参照対象>` というreSTのハイパーリンクに似た書き方をすると、タイトルと参照対象の両方を明示することができます。この場合は 参照対象 を参照するリンクになりますが、リンクテキストとして表示されるのは タイトル になります。
• 用語の先頭の文字に ! を指定すると、参照もハイパーリンクも作成されなくなります。
• Pythonオブジェクトのロールの時に、用語の先頭の文字に ~ を設定すると、リンクテキストは最後の項目だけが表示されるようになります。例えば、 :meth:`~Queue.Queue.get` というマークアップがあったとすると、 Queue.Queue.get に対して参照が作成されますが、リンクテキストとしては get が表示されます。
• HTML出力時には、リンクの title アトリビュート(マウスを上に持って行ったときにツールチップとして表示されるテキスト)には、常に、完全な参照対象の名前が設定されます。

Pythonオブジェクトのクロススリファンレス

以下のロールを使用すると、モジュール内のオブジェクトを参照することができます。一致する識別子が見つかれば、ハイパーリンクが作成されます。

:mod:

モジュールの名前です。ドットで区切られた名前も使用できます。これはパッケージ名としても利用可能です。

:func:

Pythonの関数名です。ドットで区切られた名前も使用できます。ロールのテキストは読みやすさのために括弧を後ろに含める必要はありません。 add_function_parentheses 設定値をtrue(デフォルト)にしておくと、Sphinxが自動で括弧を追加します。

:data:

モジュール変数の名前です。

:const:

定義済みの定数の名前です。これはC言語の #define や、 Pythonで変更されることのない変数に使います。

:class:

クラス名です。ドットで区切られた名前も使用できます。

:meth:

オブジェクトのメソッドの名前です。ロールのテキストには型名とメソッド名を含めなければなりません。ただし、型の記述中に書く場合には省略することもできます。ドットで区切られた名前も使用できます。

:attr:

オブジェクトの属性名です。

:exc:

例外の名前です。ドットで区切られた名前も使用できます

:obj:

型が指定されていないオブジェクトの名前です。 default_role として使用するのに便利です。

このマークアップの中の名前には、モジュール名, クラス名なども含めることができます。例えば、 :func:`filter` は現在のモジュールに定義されている filter という名前の関数か、その名前を持つ組み込み関数をあらわします。 :func:`foo.filter` と明示的に書くと、 foo モジュールの中の filter 関数を表します。

通常、これらのロールで使用される名前は、最初は修飾子なしで検索されます。次に現在のモジュール名を前に付けて検索されます。その次に現在のモジュール名とクラス名(あれば)を付けて検索されます。もし、ドットが先頭についた名前が指定された場合には、この探索順は逆になります。例えば、 codecs というPythonモジュールの定義の中で :func:`open` が定義されると、常に組み込み関数を参照しますが、 :func:`.open` と書かれると、 codecs.open() を参照するようになります。

同様の名前検索の仕組みは属性名が、現在のクラスのものかどうかというのを決定するのにも使用されます。

C言語の要素へのクロスリファレンス

以下のロールは、もしドキュメントの中に定義の説明があれば、C言語の要素へのクロスリファレンスを作成します。

:cdata:

C言語の変数の名前です

:cfunc:

C言語の関数の名前です。Pythonの関数と異なり、括弧を含む必要があります。

:cmacro:

前の説明にあるような”シンプル”なC言語のマクロ名です。

:ctype:

C言語の型名です。

他の要素へのクロスリファレンス

以下のロールはクロスリファレンスを作成しますが、特定のオブジェクトを参照しません。

:envvar:

環境変数です。エントリーのインデックスが作成されます。もし envvar ディレクティブがあれば、それへのリンクが作成されます。

:token:

文法のトークンの名前です。 productionlist ディレクティブ内の定義との間でリンクが作成されます。

:keyword:

Pythonのキーワード名です。もし存在していれば、この名前を持つ参照ラベルとの間にリンクが作成されます。

:option:

実行ファイルのコマンドラインオプションです。前に付くハイフンも含める必要があります。 cmdoption ディレクティブで定義されていれば、リンクを作成します。

以下のロールは用語集との間にクロスリファレンスを作成します:

:term:

用語集の用語への参照。用語集は glossary ディレクティブを使用して定義します。用語集と term マークアップは同じファイルにある必要はありません。例えばPythonのドキュメントは一つの用語集の glossary.rst というファイルの中にすべての用語の定義が書かれています。

もしも、用語集の中で説明されていない用語がある場合には、ビルド時に警告が出力されます。

自由な場所へのクロスリファレンス

標準のreSTのラベルを使用して、ドキュメント内の自由な位置にクロスリファレンスを作成することもできます。このラベルがきちんと動作するためには、ドキュメント全体の中で重複したラベルを使用することはできません。ラベルはユニークである必要があります。ラベルを参照する方法は２つあります。

• セクションのタイトルの直前にラベルを置くと、 :ref:`label-name` と書くことで参照できるようになります:

  .. _my-reference-label:
  
  クロスリファレンスのセクション
  ------------------------------
  
  これはセクションのテキストです。
  
  これはセクションそのものを参照します。 :ref:'my-reference-label'
  

  :ref: ロールはセクションへのリンクを作成します。リンクのタイトルは “クロスリファレンスのセクション” になります。この機能はセクションと参照が異なるソースファイルにあるときに動作します。

  自動ラベルは図に対しても動作します:

  .. _my-figure:
  
  .. figure:: whatever
  
     図のキャプション
  

  :ref:`my-figure` 参照を書くと、 “図のキャプション” というテキストを持つ、図への参照が生成されます。

• セクションタイトルの前にないラベルに対しても参照することはできますが、タイトルを明示する必要があります。この場合には :ref:`リンクラベル <ラベル名>` という文法を使用します。

これはファイルをまたいで動作するため、セクションの表題が変更されると、 ref を使用する、標準のreStructuredTextのセクション( `セクションタイトル`_ )へのリンクに対して通知されます。これはクロスリファレンスをサポートするすべてのビルダーについて言えます。

ドキュメントのクロスリファレンス

バージョン 0.6 で追加.

ドキュメントに対して直接リンクを張る方法もあります。

:doc:

ダウンロード可能なファイルへの参照

バージョン 0.6 で追加.

:download:

このロールは表示可能なreST形式ではなく、ソースツリーに存在するその他の形式のファイルへのリンクを張って、ファイルをダウンロードできるようにするときに使用します。

このロールを使用すると、HTML出力時に、参照されたファイルはビルド時に自動的に出力ディレクトリにコピーされることになります。すべてのダウンロード可能なファイルは出力ディレクトリ中の _downloads サブディレクトリ出力されます。重複した名前のファイルがあっても扱うことができます。

サンプル:

:download:`このサンプルスクリプト <../example.py>` を参照してください

与えられたファイル名は通常、そのロールが書かれているソースファイルからの相対ディレクトリで指定されますが、もし絶対パス(/ で始まる)の場合には、トップのソースディレクトリからの相対パスとして見られます。

example.py ファイルは出力ディレクトリにコピーされ、適切なリンクが生成されます。

上記以外の意味のマークアップ

以下のロールは、テキストのスタイルを変更する意外には特別なことはしません。

:abbr:

言葉の短縮形を書くのに使用します。ロールの中身として、括弧付き表現が含まれていた場合には特別扱いされます。HTMLではツールチップとして使用され、LaTeXでは一度だけ出力されます。

例: :abbr:`LIFO (last-in, first-out)`.

バージョン 0.6 で追加.

:command:

rm のような、OSレベルのコマンドの名前に使用します。

:dfn:

テキスト中の用語の定義を書くのに使用します。インデックスエントリーは作成されません。

:file:

ファイルやディレクトリの名前に使用します。ロールの中身の中には”変数”を表す波括弧を含めることができます。例:

... は :file:`/usr/lib/python2.{x}/site-packages` にインストールされます ...

ドキュメントのビルドの中で、 x Pythonのマイナーバージョンを表す文字に置き換えられて表示されます。

:guilabel:

インタラクティブなユーザインタフェースの一部のラベルとして表示あれる文字に対しては guilabel を使用します。これは、 curses やその他のコンソール用ライブラリを使用したテキストベースのインタフェースにも使用します。ボタンやウィンドウのタイトル、フィールド名、メニュー、やメニューの項目名、リスト中の選択された値など、インタフェース上に表示されるラベルには、このロールを使用すべきです。

:kbd:

キーボード操作のキーに使用します。 キー操作をどのように表現するかはプラットフォームや、アプリケーション上の慣習の影響を受けます。もし、慣習に関しての制約がない場合には、修飾キー(Shiftなど)の名前は、省略せずにきちんと書くと、新規ユーザと、英語がネイティブでないユーザから見たアクセシビリティは向上します。例えば、*xemacs* キー操作は :kbd:`C-x C-f` という表現になるでしょう。しかし、特定のアプリケーションやプラットフォームに限定する必要がなければ同じ操作は :kbd:`Control-x Control-f` と書くべきです。

:mailheader:

RFC 822の形式のメールヘッダの名前に使用します。これでマークアップされたヘッダは電子メールのメッセージの中で必ず使用されている必要はありませんが、参照するのに他のヘッダと同じ形式を使用することが可能です。このヘッダはさまざまなMIMEの使用で定義されたヘッダに対しても使用することができます。ヘッダ名は実際に電子メール内で使用されるのと同じ形式(キャメルケース)で書かれるべきです。例えば、 :mailheader:`Content-Type` という形式になります。

:makevar:

make の変数名です。

:manpage:

セクションの内容を含むUnixのマニュアルページへの参照です。 例: :manpage:`ls(1)`

:menuselection:

メニュー選択は menuselection ロールを使用すべきです。これはメニュー操作の手順をマークアップするのに使用します。メニューにはメニュー選択、サブメニュー選択、特定の操作での選択や、さらに細かいサブ操作などを含みます。それぞれの選択要素の名前は --> を使用して分割すべきです。

例えば、”スタート > プログラム”という順番でメニューを選択する動作は以下のように記述します:

:menuselection:`スタート --> プログラム`

:mimetype:

MIMEタイプの名前、もしくはの一部MIMEタイプ(メジャー、マイナー部分、もしくは単独)を表します。

:newsgroup:

USENETのニュースグループ名です。

:program:

実行プログラムの名前です。これはプラットフォームによって名前が変化することもあります。特にWindowsのプログラムのための .exe やそれ以外の拡張子はは省略すべきです。

:regexp:

正規表現です。引用符は含めることはできません。

:samp:

リテラルのテキストの一部です。マークアップの内容の中には、 :file: と同様に波括弧を使った”変数”を書くことができます。

もし”変数部分”が不要であれば、標準の ``コード`` という形式を代わりに使用してください。

下記のロールは外部へのリンクを生成します。

:pep:

Python拡張提案書(PEP)への参照です。これは適切なインデックスのエントリーを作成します。”PEP number“という形式のテキストが作成されます。HTML出力ではこのテキストは特定のPEPのオンラインのコピーへのハイパーリンクとなります。

:rfc:

インターネットのRFCへの参照です。これは適切なインデックスのエントリーを作成します。”RFC number“という形式のテキストが作成されます。HTML出力ではこのテキストは特定のRFCのオンラインのコピーへのハイパーリンクとなります。

このような目的を達成しようとしても、標準のreSTマークアップだけではハイパーリンクを取り込む特別なロールは存在しません。

置換

デフォルトでは3つの代数がドキュメントシステムから提供されています。これらはビルドの設定ファイルの中で設定されます。

|release|

ドキュメントが参照しているプロジェクトのリリースと置き換えられます。これは、 2.5.2b3 などのような、alpha/beta/release candidateタグも含めた完全なバージョン文字列と置換されます。 release を使って設定します。

|version|

ドキュメントが参照しているプロジェクトのリリースと置き換えられます。これは、メジャーバージョン、マイナーバージョンのっぶんだけを含む文字列です。例えば、``2.5.1`` というのがあったとすると、 2.5 になります。 version を使って設定します。

|today|

本日の日付に置き換えられます。日付はドキュメントが読み込まれた日になります。もしくはビルド設定ファイルにて日付を設定することも可能です。通常は April 14, 2007 というフォーマットが使用されます。 today_fmt と today を設定することで変更することができます。