Home | Symfony2Doc »Symfony2 プロジェクトへの貢献 »ドキュメントへの貢献 »ドキュメントのフォーマット

ご注意

Symfony2日本語翻訳ドキュメントは内容が古くなっております。公式サイトの英語ドキュメントを参照してください。

ドキュメントのフォーマット

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 ディレクティブを使い、サポートされているすべての設定フォーマット (PHPYAMLXML) を表示できるようにします。

.. 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; をインストールします。
  • Sphinx quick setup; を実行します。
  • 設定ブロックの 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']
blog comments powered by Disqus