ナビゲーション
- 索引
- モジュール |
- 次へ |
- 前へ |
- Python 2.7ja1 documentation »
- Python のドキュメントの作成 »
マークアップ言語は変わりましたが、もとの LaTeX ドキュメントにあったコンセプトやドキュメント型(markup types) はほとんど残っています – 環境(environments) は reST ディレクティブ、インラインコマンドは reST roles などなど。
しかし、それらがどう動作するのか(the way these work)については、マークアップ言語の違いのため、もしくは Sphinx の改善のために、いくらか異なっています。このセクションでは、古いフォーマットに慣れた人に新しいフォーマットでどう変わったのか概要を示すために、違いをリストアップしていきます。
インラインマークアップには以下の変更点があります:
クロスリファレンス roles
以下の semantic roles は以前はインラインコマンドで、 code としてフォーマットする以外には何もしませんでした。今は、既知のターゲットに対してクロスリファレンスになります。 (あと、いくつかの名前は短くなっています):
func と meth の扱いにも違いがあります: 以前は丸括弧を呼び出し可能オブジェクト名の後ろに (\func{str()} のように) 書きましたが、ビルドシステムが丸括弧をつけるようになりました。 – ソースファイルに丸括弧を書くと、出力では二重に括弧がついてしまいます。 :func:`str(object)` も期待通りになりません。代わりに ``str(object)`` を使ってください!
インラインコマンドはディレクティブとして実装されました
LaTeX にはインラインコマンドがありましたが、 reST ではディレクティブになりました:
次のようにして使います:
.. deprecated:: 2.5
Reason of deprecation.
同じく、 versionadded と versionchanged のテキストにはピリオドがつきません。 versionchanged.
これらは次のように使います:
.. note::
Content of note.
その他の変更されたコマンド
以前の samp コマンドは、 code フォーマットでクォーテーションマークで囲まれていました。 samp role では、 file と同じくコードハイライトの機能が新しく追加されました:
:samp:`open({filename}, {mode})` results in open(filename, mode)
無くなったコマンド
次の LaTeX にあったコマンドは、現在 role では対応していません:
バックスラッシュによるエスケープ
reSTでは、バックスラッシュは通常のテキストや role の中ではエスケープしないといけません。しかし、 code リテラルやリテラルブロックではエスケープしてはいけません。例えば: :file:`C:\\Temp\\my.tmp` vs. ``open("C:\Temp\my.tmp")``.
情報単位(information units) (latexでは ...desc という環境) は reST ディレクティブで作ります。説明しておかないといけない情報単位に関する変更点は:
新しい名前 すべての名前から “desc” が無くなりました。新しい名前は:
classdesc と excclassdesc 環境は無くなりました。代わりに、 class と exception ディレクティブがコンストラクタの引数あり・なしでクラスのドキュメントをサポートします。
複数のオブジェクト ...line というコマンドと等価なのは:
.. function:: do_foo(bar)
do_bar(baz)
Description of the functions.
言い換えると、同じインデントレベルに複数のシグネチャを一行ずつ書くだけです。
引数
optional コマンドはありません。単純に関数のシグネチャを出力で表示されるのと同じ形で書いてください。
.. function:: open(filename[, mode[, buffering]])
Description.
注意: シグネチャの中ではマークアップはサポートされません。
Indexing
...descni 環境は無くなりました。情報単位をインデックスエントリに含めないようにするには、 noindex オプションを次のように利用してください:
.. function:: foo_*
:noindex:
Description.
新しい情報単位
新しい汎用情報単位があります。一つは “describe” と呼ばれ、他の情報単位の対象にならない単位に使うことができます:
.. describe:: a == b
The equals operator.
他には次のような単位があります:
.. cmdoption:: -O
Describes a command-line option.
.. envvar:: PYTHONINSPECT
Describes an environment variable.
LaTeX ドキュメントはいくつかのトップレベルマニュアルに分割されていました。今は、すべてのファイルは toctree ディレクティブで指定される一つのドキュメントツリーの一部です。 (各出力フォーマットでまたファイルを分割することもできます) すべての toctree ディレクティブは他のファイルを現在のファイルのサブドキュメントとして埋め込みます。 (この構造をファイルシステムレイアウトに反映させる必要はありません) トップレベルのファイルは contents.rst です。
しかし、今までのディレクトリ構造の大部分は、次のように名前を変更されながら残っています: