.. highlight:: rest .. Inline markup .. ============= インラインマークアップ ====================== .. Sphinx uses interpreted text roles to insert semantic markup into documents. They are written as ``:rolename:`content```. Sphinxは解釈済みのテキストのロールというものを使用して、用語の意味を記述して、リンクを張ったりすることができます。これを記述する時は ``:ロール名:`内容``` というフォーマットで記述します。 .. note:: デフォルトのロール(```content```)には標準では特別な意味を持っていません。必要に応じてどのように使用してもかまいません。例えば変数名として使用する、などです。 :confval:`default_role` という設定値を変更することで、デフォルトのロールに対して、既存のロールを設定することができます。 .. The default role (```content```) has no special meaning by default. You are free to use it for anything you like, e.g. variable names; use the :confval:`default_role` config value to set it to a known role. .. Cross-referencing syntax ------------------------ .. _xref-syntax: クロスリファレンス文法 ---------------------- .. Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write ``:role:`target```, and a link will be created to the item named *target* of the type indicated by *role*. The links's text will be the same as *target*. クロスリファレンスは、意味解釈済みのテキストロールから生成されます。基本的には ``:ロール:`用語``` という形式で書くだけでクロスリファレンスを作成することができます。このときは *用語* というアイテム名で、 *ロール* で指定されたタイプを持つリンクが作成されます。リンクに表示されるテキストは *用語* と同じになります。 .. There are some additional facilities, however, that make cross-referencing roles more versatile .. * You may supply an explicit title and reference target, like in reST direct hyperlinks: ``:role:`title ``` will refer to *target*, but the link text will be *title*. .. * If you prefix the content with ``!``, no reference/hyperlink will be created. .. * For the Python object roles, if you prefix the content with ``~``, the link text will only be the last component of the target. For example, ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only display ``get`` as the link text. .. In HTML output, the link's ``title`` attribute (that is e.g. shown as a tool-tip on mouse-hover) will always be the full target name. 追加の補助機能がいくつかありますが、これはロールに対するクロスリファレンスの目的を増やすものになります。: * ``:ロール:`タイトル <参照対象>``` というreSTのハイパーリンクに似た書き方をすると、タイトルと参照対象の両方を明示することができます。この場合は *参照対象* を参照するリンクになりますが、リンクテキストとして表示されるのは *タイトル* になります。 * 用語の先頭の文字に ``!`` を指定すると、参照もハイパーリンクも作成されなくなります。 * Pythonオブジェクトのロールの時に、用語の先頭の文字に ``~`` を設定すると、リンクテキストは最後の項目だけが表示されるようになります。例えば、 ``:meth:`~Queue.Queue.get``` というマークアップがあったとすると、 ``Queue.Queue.get`` に対して参照が作成されますが、リンクテキストとしては ``get`` が表示されます。 * HTML出力時には、リンクの ``title`` アトリビュート(マウスを上に持って行ったときにツールチップとして表示されるテキスト)には、常に、完全な参照対象の名前が設定されます。 .. Cross-referencing Python objects -------------------------------- Pythonオブジェクトのクロススリファンレス ---------------------------------------- .. The following roles refer to objects in modules and are possibly hyperlinked if a matching identifier is found: 以下のロールを使用すると、モジュール内のオブジェクトを参照することができます。一致する識別子が見つかれば、ハイパーリンクが作成されます。 .. role:: mod モジュールの名前です。ドットで区切られた名前も使用できます。これはパッケージ名としても利用可能です。 .. The name of a module; a dotted name may be used. This should also be used for package names. .. role:: func Pythonの関数名です。ドットで区切られた名前も使用できます。ロールのテキストは読みやすさのために括弧を後ろに含める必要はありません。 :confval:`add_function_parentheses` 設定値をtrue(デフォルト)にしておくと、Sphinxが自動で括弧を追加します。 .. The name of a Python function; dotted names may be used. The role text needs not include trailing parentheses to enhance readability; they will be added automatically by Sphinx if the :confval:`add_function_parentheses` config value is true (the default). .. role:: data モジュール変数の名前です。 .. The name of a module-level variable. .. role:: const 定義済みの定数の名前です。これはC言語の ``#define`` や、 Pythonで変更されることのない変数に使います。 .. The name of a "defined" constant. This may be a C-language ``#define`` or a Python variable that is not intended to be changed. .. role:: class クラス名です。ドットで区切られた名前も使用できます。 .. A class name; a dotted name may be used. .. role:: meth オブジェクトのメソッドの名前です。ロールのテキストには型名とメソッド名を含めなければなりません。ただし、型の記述中に書く場合には省略することもできます。ドットで区切られた名前も使用できます。 .. The name of a method of an object. The role text should include the type name and the method name; if it occurs within the description of a type, the type name can be omitted. A dotted name may be used. .. role:: attr オブジェクトの属性名です。 .. The name of a data attribute of an object. .. role:: exc 例外の名前です。ドットで区切られた名前も使用できます .. The name of an exception. A dotted name may be used. .. role:: obj 型が指定されていないオブジェクトの名前です。 :confval:`default_role` として使用するのに便利です。 .. The name of an object of unspecified type. Useful e.g. as the :confval:`default_role`. .. versionadded:: 0.4 .. The name enclosed in this markup can include a module name and/or a class name. For example, ``:func:`filter``` could refer to a function named ``filter`` in the current module, or the built-in function of that name. In contrast, ``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo`` module. このマークアップの中の名前には、モジュール名, クラス名なども含めることができます。例えば、 ``:func:`filter``` は現在のモジュールに定義されている ``filter`` という名前の関数か、その名前を持つ組み込み関数をあらわします。 ``:func:`foo.filter``` と明示的に書くと、 ``foo`` モジュールの中の ``filter`` 関数を表します。 .. Normally, names in these roles are searched first without any further qualification, then with the current module name prepended, then with the current module and class name (if any) prepended. If you prefix the name with a dot, this order is reversed. For example, in the documentation of Python's :mod:`codecs` module, ``:func:`open``` always refers to the built-in function, while ``:func:`.open``` refers to :func:`codecs.open`. 通常、これらのロールで使用される名前は、最初は修飾子なしで検索されます。次に現在のモジュール名を前に付けて検索されます。その次に現在のモジュール名とクラス名(あれば)を付けて検索されます。もし、ドットが先頭についた名前が指定された場合には、この探索順は逆になります。例えば、 :mod:`codecs` というPythonモジュールの定義の中で ``:func:`open``` が定義されると、常に組み込み関数を参照しますが、 ``:func:`.open``` と書かれると、 :func:`codecs.open` を参照するようになります。 .. A similar heuristic is used to determine whether the name is an attribute of the currently documented class. 同様の名前検索の仕組みは属性名が、現在のクラスのものかどうかというのを決定するのにも使用されます。 .. Cross-referencing C constructs ------------------------------ C言語の要素へのクロスリファレンス --------------------------------- .. The following roles create cross-references to C-language constructs if they are defined in the documentation: 以下のロールは、もしドキュメントの中に定義の説明があれば、C言語の要素へのクロスリファレンスを作成します。 .. role:: cdata C言語の変数の名前です .. The name of a C-language variable. .. role:: cfunc C言語の関数の名前です。Pythonの関数と異なり、括弧を含む必要があります。 .. The name of a C-language function. Should include trailing parentheses. .. role:: cmacro 前の説明にあるような"シンプル"なC言語のマクロ名です。 .. The name of a "simple" C macro, as defined above. .. role:: ctype C言語の型名です。 .. The name of a C-language type. .. Cross-referencing other items of interest ----------------------------------------- 他の要素へのクロスリファレンス ------------------------------ .. The following roles do possibly create a cross-reference, but do not refer to objects: 以下のロールはクロスリファレンスを作成しますが、特定のオブジェクトを参照しません。 .. role:: envvar 環境変数です。エントリーのインデックスが作成されます。もし :dir:`envvar` ディレクティブがあれば、それへのリンクが作成されます。 .. An environment variable. Index entries are generated. Also generates a link to the matching :dir:`envvar` directive, if it exists. .. role:: token 文法のトークンの名前です。 :dir:`productionlist` ディレクティブ内の定義との間でリンクが作成されます。 .. The name of a grammar token (used to create links between :dir:`productionlist` directives). .. role:: keyword Pythonのキーワード名です。もし存在していれば、この名前を持つ参照ラベルとの間にリンクが作成されます。 .. The name of a keyword in Python. This creates a link to a reference label with that name, if it exists. .. role:: option 実行ファイルのコマンドラインオプションです。前に付くハイフンも含める必要があります。 :dir:`cmdoption` ディレクティブで定義されていれば、リンクを作成します。 .. A command-line option to an executable program. The leading hyphen(s) must be included. This generates a link to a :dir:`cmdoption` directive, if it exists. .. The following role creates a cross-reference to the term in the glossary: 以下のロールは用語集との間にクロスリファレンスを作成します: .. role:: term 用語集の用語への参照。用語集は ``glossary`` ディレクティブを使用して定義します。用語集と ``term`` マークアップは同じファイルにある必要はありません。例えばPythonのドキュメントは一つの用語集の ``glossary.rst`` というファイルの中にすべての用語の定義が書かれています。 もしも、用語集の中で説明されていない用語がある場合には、ビルド時に警告が出力されます。 .. Reference to a term in the glossary. The glossary is created using the ``glossary`` directive containing a definition list with terms and definitions. It does not have to be in the same file as the ``term`` markup, for example the Python docs have one global glossary in the ``glossary.rst`` file. .. If you use a term that's not explained in a glossary, you'll get a warning during build. .. Cross-referencing arbitrary locations ------------------------------------- .. _ref-role: 自由な場所へのクロスリファレンス -------------------------------- .. index:: pair: ref; role .. To support cross-referencing to arbitrary locations in any document, the standard reST labels are used. For this to work label names must be unique throughout the entire documentation. There are two ways in which you can refer to labels: 標準のreSTのラベルを使用して、ドキュメント内の自由な位置にクロスリファレンスを作成することもできます。このラベルがきちんと動作するためには、ドキュメント全体の中で重複したラベルを使用することはできません。ラベルはユニークである必要があります。ラベルを参照する方法は２つあります。 .. * If you place a label directly before a section title, you can reference to it with ``:ref:`label-name```. Example:: .. .. _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`. .. The ``:ref:`` role would then generate a link to the section, with the link title being "Section to cross-reference". This works just as well when section and reference are in different source files. .. Automatic labels also work with figures: given :: .. .. _my-figure: .. .. figure:: whatever .. Figure caption .. a reference ``:ref:`my-figure``` would insert a reference to the figure with link text "Figure caption". * セクションのタイトルの直前にラベルを置くと、 ``:ref:`label-name``` と書くことで参照できるようになります:: .. _my-reference-label: クロスリファレンスのセクション ------------------------------ これはセクションのテキストです。 これはセクションそのものを参照します。 :ref:'my-reference-label' ``:ref:`` ロールはセクションへのリンクを作成します。リンクのタイトルは "クロスリファレンスのセクション" になります。この機能はセクションと参照が異なるソースファイルにあるときに動作します。 自動ラベルは図に対しても動作します:: .. _my-figure: .. figure:: whatever 図のキャプション ``:ref:`my-figure``` 参照を書くと、 "図のキャプション" というテキストを持つ、図への参照が生成されます。 .. * Labels that aren't placed before a section title can still be referenced to, but you must give the link an explicit title, using this syntax: ``:ref:`Link title ```. * セクションタイトルの前にないラベルに対しても参照することはできますが、タイトルを明示する必要があります。この場合には ``:ref:`リンクラベル <ラベル名>``` という文法を使用します。 .. Using :role:`ref` is advised over standard reStructuredText links to sections (like ```Section title`_``) because it works across files, when section headings are changed, and for all builders that support cross-references. これはファイルをまたいで動作するため、セクションの表題が変更されると、 :role:`ref` を使用する、標準のreStructuredTextのセクション( ```セクションタイトル`_`` )へのリンクに対して通知されます。これはクロスリファレンスをサポートするすべてのビルダーについて言えます。 .. Cross-referencing documents --------------------------- ドキュメントのクロスリファレンス --------------------------------- .. versionadded:: 0.6 .. There is also a way to directly link to documents: ドキュメントに対して直接リンクを張る方法もあります。 .. role:: doc .. Link to the specified document; the document name can be specified in .. absolute or relative fashion. For example, if the reference .. ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link .. refers to ``sketches/parrot``. If the reference is ``:doc:`/people``` or .. ``:doc:`../people```, the link refers to ``people``. .. If no explicit link text is given (like usual: ``:doc:`Monty Python members .. ```), the link caption will be the title of the given document. 絶対/相対のどちらかの形式でドキュメント名を指定することで、特定のドキュメントに対してリンクを張ることができます。例えば、 ``:doc:`parrot``` という参照が ``sketches/index`` というファイルの中にあったとすると、 ``skethes/parrot`` に対するリンクとなります。もし参照が ``:doc:`/people``` もしくは ``:doc:`../people``` という形式で書かれている場合には ``people`` に対するリンクが作成されます。 ``:doc:`Monty Python members ``` という形式で、明示的にリンクテキストを指定することができますが、もし明示的なリンクテキストが与えられなかった場合には指定されたドキュメントのタイトルがリンクテキストとなります。 .. Referencing downloadable files .. ------------------------------ ダウンロード可能なファイルへの参照 ---------------------------------- .. versionadded:: 0.6 .. role:: download このロールは表示可能なreST形式ではなく、ソースツリーに存在するその他の形式のファイルへのリンクを張って、ファイルをダウンロードできるようにするときに使用します。 このロールを使用すると、HTML出力時に、参照されたファイルはビルド時に自動的に出力ディレクトリにコピーされることになります。すべてのダウンロード可能なファイルは出力ディレクトリ中の ``_downloads`` サブディレクトリ出力されます。重複した名前のファイルがあっても扱うことができます。 サンプル:: :download:`このサンプルスクリプト <../example.py>` を参照してください 与えられたファイル名は通常、そのロールが書かれているソースファイルからの相対ディレクトリで指定されますが、もし絶対パス(``/`` で始まる)の場合には、トップのソースディレクトリからの相対パスとして見られます。 ``example.py`` ファイルは出力ディレクトリにコピーされ、適切なリンクが生成されます。 .. This role lets you link to files within your source tree that are not reST .. documents that can be viewed, but files that can be downloaded. .. When you use this role, the referenced file is automatically marked for .. inclusion in the output when building (obviously, for HTML output only). .. All downloadable files are put into the ``_downloads`` subdirectory of the .. output directory; duplicate filenames are handled. .. An example .. See :download:`this example script <../example.py>`. .. The given filename is usually relative to the directory the current sourc .. file is contained in, but if it absolute (starting with ``/``), it is taken .. as relative to the top source directory. .. The ``example.py`` file will be copied to the output directory, and a .. suitable link generated to it. .. Other semantic markup .. --------------------- 上記以外の意味のマークアップ ----------------------------- .. The following roles don't do anything special except formatting the text in a different style: 以下のロールは、テキストのスタイルを変更する意外には特別なことはしません。 .. role:: abbr 言葉の短縮形を書くのに使用します。ロールの中身として、括弧付き表現が含まれていた場合には特別扱いされます。HTMLではツールチップとして使用され、LaTeXでは一度だけ出力されます。 例: ``:abbr:`LIFO (last-in, first-out)```. .. versionadded:: 0.6 .. An abbreviation. If the role content contains a parenthesized explanation, it will be treated specially: it will be shown in a tool-tip in HTML, and output only once in LaTeX. .. Example: ``:abbr:`LIFO (last-in, first-out)```. .. role:: command ``rm`` のような、OSレベルのコマンドの名前に使用します。 .. The name of an OS-level command, such as ``rm``. .. role:: dfn テキスト中の用語の定義を書くのに使用します。インデックスエントリーは作成されません。 .. Mark the defining instance of a term in the text. (No index entries are generated.) .. role:: file ファイルやディレクトリの名前に使用します。ロールの中身の中には"変数"を表す波括弧を含めることができます。例:: ... は :file:`/usr/lib/python2.{x}/site-packages` にインストールされます ... ドキュメントのビルドの中で、 ``x`` Pythonのマイナーバージョンを表す文字に置き換えられて表示されます。 .. The name of a file or directory. Within the contents, you can use curly braces to indicate a "variable" part, for example:: .. ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ... .. In the built documentation, the ``x`` will be displayed differently to indicate that it is to be replaced by the Python minor version. .. role:: guilabel インタラクティブなユーザインタフェースの一部のラベルとして表示あれる文字に対しては ``guilabel`` を使用します。これは、 :mod:`curses` やその他のコンソール用ライブラリを使用したテキストベースのインタフェースにも使用します。ボタンやウィンドウのタイトル、フィールド名、メニュー、やメニューの項目名、リスト中の選択された値など、インタフェース上に表示されるラベルには、このロールを使用すべきです。 .. Labels presented as part of an interactive user interface should be marked using ``guilabel``. This includes labels from text-based interfaces such as those created using :mod:`curses` or other text-based libraries. Any label used in the interface should be marked with this role, including button labels, window titles, field names, menu and menu selection names, and even values in selection lists. .. role:: kbd キーボード操作のキーに使用します。 キー操作をどのように表現するかはプラットフォームや、アプリケーション上の慣習の影響を受けます。もし、慣習に関しての制約がない場合には、修飾キー(Shiftなど)の名前は、省略せずにきちんと書くと、新規ユーザと、英語がネイティブでないユーザから見たアクセシビリティは向上します。例えば、*xemacs* キー操作は ``:kbd:`C-x C-f``` という表現になるでしょう。しかし、特定のアプリケーションやプラットフォームに限定する必要がなければ同じ操作は ``:kbd:`Control-x Control-f``` と書くべきです。 .. Mark a sequence of keystrokes. What form the key sequence takes may depend on platform- or application-specific conventions. When there are no relevant conventions, the names of modifier keys should be spelled out, to improve accessibility for new users and non-native speakers. For example, an *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without reference to a specific application or platform, the same sequence should be marked as ``:kbd:`Control-x Control-f```. .. role:: mailheader RFC 822の形式のメールヘッダの名前に使用します。これでマークアップされたヘッダは電子メールのメッセージの中で必ず使用されている必要はありませんが、参照するのに他のヘッダと同じ形式を使用することが可能です。このヘッダはさまざまなMIMEの使用で定義されたヘッダに対しても使用することができます。ヘッダ名は実際に電子メール内で使用されるのと同じ形式(キャメルケース)で書かれるべきです。例えば、 ``:mailheader:`Content-Type``` という形式になります。 .. The name of an RFC 822-style mail header. This markup does not imply that the header is being used in an email message, but can be used to refer to any header of the same "style." This is also used for headers defined by the various MIME specifications. The header name should be entered in the same way it would normally be found in practice, with the camel-casing conventions being preferred where there is more than one common usage. For example: ``:mailheader:`Content-Type```. .. role:: makevar :command:`make` の変数名です。 .. The name of a :command:`make` variable. .. role:: manpage セクションの内容を含むUnixのマニュアルページへの参照です。 例: ``:manpage:`ls(1)``` .. A reference to a Unix manual page including the section, .. e.g. ``:manpage:`ls(1)```. .. role:: menuselection メニュー選択は ``menuselection`` ロールを使用すべきです。これはメニュー操作の手順をマークアップするのに使用します。メニューにはメニュー選択、サブメニュー選択、特定の操作での選択や、さらに細かいサブ操作などを含みます。それぞれの選択要素の名前は ``-->`` を使用して分割すべきです。 例えば、"スタート > プログラム"という順番でメニューを選択する動作は以下のように記述します:: :menuselection:`スタート --> プログラム` .. Menu selections should be marked using the ``menuselection`` role. This is used to mark a complete sequence of menu selections, including selecting submenus and choosing a specific operation, or any subsequence of such a sequence. The names of individual selections should be separated by ``-->``. .. For example, to mark the selection "Start > Programs", use this markup:: .. :menuselection:`Start --> Programs` もし、選択したメニューにはオペレーティングシステム固有のコマンドの指示などが含まれていた場合には、これは省略すべきです。例えば、ダイアログを開くコマンドなどです。このようなコマンドの指示は選択名からは省きます。 .. When including a selection that includes some trailing indicator, such as the ellipsis some operating systems use to indicate that the command opens a dialog, the indicator should be omitted from the selection name. .. role:: mimetype MIMEタイプの名前、もしくはの一部MIMEタイプ(メジャー、マイナー部分、もしくは単独)を表します。 .. The name of a MIME type, or a component of a MIME type (the major or minor portion, taken alone). .. role:: newsgroup USENETのニュースグループ名です。 .. The name of a Usenet newsgroup. .. role:: program 実行プログラムの名前です。これはプラットフォームによって名前が変化することもあります。特にWindowsのプログラムのための ``.exe`` やそれ以外の拡張子はは省略すべきです。 .. The name of an executable program. This may differ from the file name for the executable for some platforms. In particular, the ``.exe`` (or other) extension should be omitted for Windows programs. .. role:: regexp 正規表現です。引用符は含めることはできません。 .. A regular expression. Quotes should not be included. .. role:: samp リテラルのテキストの一部です。マークアップの内容の中には、 ``:file:`` と同様に波括弧を使った"変数"を書くことができます。 もし"変数部分"が不要であれば、標準の ````コード```` という形式を代わりに使用してください。 .. A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a "variable" part, as in ``:file:``. .. If you don't need the "variable part" indication, use the standard ````code```` instead. .. The following roles generate external links: 下記のロールは外部へのリンクを生成します。 .. role:: pep Python拡張提案書(PEP)への参照です。これは適切なインデックスのエントリーを作成します。"PEP *number*\ "という形式のテキストが作成されます。HTML出力ではこのテキストは特定のPEPのオンラインのコピーへのハイパーリンクとなります。 .. A reference to a Python Enhancement Proposal. This generates appropriate index entries. The text "PEP *number*\ " is generated; in the HTML output, this text is a hyperlink to an online copy of the specified PEP. .. role:: rfc インターネットのRFCへの参照です。これは適切なインデックスのエントリーを作成します。"RFC *number*\ "という形式のテキストが作成されます。HTML出力ではこのテキストは特定のRFCのオンラインのコピーへのハイパーリンクとなります。 .. A reference to an Internet Request for Comments. This generates appropriate index entries. The text "RFC *number*\ " is generated; in the HTML output, this text is a hyperlink to an online copy of the specified RFC. .. Note that there are no special roles for including hyperlinks as you can use the standard reST markup for that purpose. このような目的を達成しようとしても、標準のreSTマークアップだけではハイパーリンクを取り込む特別なロールは存在しません。 .. _default-substitutions: .. Substitutions .. ------------- 置換 ---- .. The documentation system provides three substitutions that are defined by default. They are set in the build configuration file. デフォルトでは3つの代数がドキュメントシステムから提供されています。これらはビルドの設定ファイルの中で設定されます。 .. describe:: |release| ドキュメントが参照しているプロジェクトのリリースと置き換えられます。これは、 ``2.5.2b3`` などのような、alpha/beta/release candidateタグも含めた完全なバージョン文字列と置換されます。 :confval:`release` を使って設定します。 .. Replaced by the project release the documentation refers to. This is meant to be the full version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``. Set by :confval:`release`. .. describe:: |version| ドキュメントが参照しているプロジェクトのリリースと置き換えられます。これは、メジャーバージョン、マイナーバージョンのっぶんだけを含む文字列です。例えば、``2.5.1`` というのがあったとすると、 ``2.5`` になります。 :confval:`version` を使って設定します。 .. Replaced by the project version the documentation refers to. This is meant to consist only of the major and minor version parts, e.g. ``2.5``, even for version 2.5.1. Set by :confval:`version`. .. describe:: |today| 本日の日付に置き換えられます。日付はドキュメントが読み込まれた日になります。もしくはビルド設定ファイルにて日付を設定することも可能です。通常は ``April 14, 2007`` というフォーマットが使用されます。 :confval:`today_fmt` と :confval:`today` を設定することで変更することができます。 .. Replaced by either today's date (the date on which the document is read), or the date set in the build configuration file. Normally has the format ``April 14, 2007``. Set by :confval:`today_fmt` and :confval:`today`.