絶対/相対のどちらかの形式でドキュメント名を指定することで、特定のドキュメントに対してリンクを張ることができます。例えば、 :doc:`parrot` という参照が sketches/index というファイルの中にあったとすると、 skethes/parrot に対するリンクとなります。もし参照が :doc:`/people` もしくは :doc:`../people` という形式で書かれている場合には people に対するリンクが作成されます。

:doc:`Monty Python members </people>` という形式で、明示的にリンクテキストを指定することができますが、もし明示的なリンクテキストが与えられなかった場合には指定されたドキュメントのタイトルがリンクテキストとなります。

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

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

サンプル:

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

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

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

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

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

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

例: LIFO.

New in version 0.6.

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

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

Changed in version 1.0.

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

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

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

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

リテラルのテキストの一部です。マークアップの内容の中には、 file と同様に波括弧を使った”変数”を書くことができます。たとえば、 print 1+variable というテキストがあると、 variable の部分が強調されます。

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