ドキュメントのフォーマット¶
Symfony2 のドキュメントはマークアップ言語として reStructuredText を使っており、Sphinx を使って HTML、PDF などのドキュメントを出力しています。
reStructuredText¶
reStructuredText は、「読みやすく、見たままのプレーンテキストマークアップ構文をパースするシステム」です。
構文について詳しく学びたい方は、Symfony2 のドキュメントのソースを読むか、Sphinx Web サイトのreStructuredText Primerを読んでください。
Markdown フォーマットを扱ったことがあるなら、次のような似ているが異なる構文に注意してください。
- リストは行の先頭で開始します (インデントはできません)
- インラインのコードブロックには 2 重のバッククォートを使います (``このように``)。
Sphinx¶
Sphinx は、reStructuredText ファイルからドキュメントを生成するビルドシステムで、いくつかのすばらしい機能があります。 たとえば、標準的な、reST マークアップのほかに、ディレクディブやテキストロールが追加されています。
構文のハイライト¶
すべてのサンプルコードは、ハイライトされるデフォルトの言語として PHP を使います。 このデフォルト設定は、次のように code-block ディレクティブで変更できます。
.. code-block:: yaml
{ foo: bar, bar: { foo: bar, bar: baz } }
PHP コードが <?php で始まる場合、ハイライト用の擬似言語として html+php を使ってください。
.. code-block:: html+php
<?php echo $this->foobar(); ?>
Note
ハイライトがサポートされている言語の一覧は、 Pygments website をご確認ください。
設定ブロック¶
設定を表示する場合は configuration-block ディレクティブを使い、サポートされているすべての設定フォーマット (PHP、YAML、XML) を表示できるようにします。
.. configuration-block::
.. code-block:: yaml
# YAML での設定
.. code-block:: xml
<!-- XML での設定 //-->
.. code-block:: php
// PHP での設定
この reST スニペットは、次のようにレンダリングされます。
-
YAML
# YAML での設定 -
XML
<!-- XML での設定 //--> -
PHP
// PHP での設定
現在サポートされているフォーマットの一覧は以下のとおりです。
| マークアップフォーマット | 表示 |
|---|---|
| html xml php yaml jinja html+jinja jinja+html php+html html+php ini php-annotations | HTML XML PHP YAML Twig Twig Twig PHP PHP INI Annotations |
ドキュメントのテスト¶
コミット前にドキュメントをテストするには、次の手順に従います。
- 設定ブロックの Sphinx エクステンションをインストールします (下の項を参照)。
- make html を実行し、 build ディレクトリ内に生成された HTML を確認します。
設定ブロックの Sphinx エクステンションのインストール¶
- configuration-block source リポジトリからエクステンションをダウンロードします。
- configurationblock.py をソースフォルダ内の _exts にコピーします (conf.py が置かれているフォルダです) 。
- conf.py ファイルに以下を追加します。
# ...
sys.path.append(os.path.abspath('_exts'))
# ...
# エクステンションのリストに configurationblock を追加
extensions = ['configurationblock']