ドキュメント

ドキュメントへの貢献の方法はシンプルです。 ファイルは https://github.com/cakephp/docs にホストされています。 自由にレポジトリをフォークして、変更・改善・翻訳を追加し、プルリクエストを発行してください。 またファイルをダウンロードせず、GitHubを使ってオンラインでドキュメントを編集することもできます。

翻訳

ドキュメントチーム(docs at cakephp dot org)までEメールを送るか、IRC (#cakephp on freenode)で、参加したい旨を連絡してください。

翻訳者tips:

• 翻訳する言語のページで閲覧・編集してください。 そうしないと、どこが既に翻訳されているかわからないでしょう。
• この本の中に読みたい言語を見つけたら、どうぞ遠慮なくご覧ください。
• フレンドリーな文体 を使ってください。
• タイトルと内容を同時に翻訳してください。
• 修正を投稿する前に、英語版との比較を行うようにしてください。 どこかを修正しても、以前の変更が統合されていなかったら、投稿したものが受け付けられないことがあります。
• 用語を英語で書く場合には、 <em> タグで囲んでください。 例えば、「asdf asdf Controller asdf」 や 「asdf asdf Kontroller (Controller) asfd」 などです。
• 一部だけ翻訳して投稿しないでください。
• 保留されている項目があるセクションは編集しないでください。
• アクセント文字のために HTML エンティティ を使用しないでください。 この本はUTF-8を使っています。
• 記述(HTML)の変更や新しいコンテンツを、一度にたくさん加えないでください。
• 元のコンテンツに不備がある場合は、まずそれを編集するようにしてください。

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

新しいCakePHPのドキュメントはReSTフォーマットテキストで書かれています。 ReST(Re Structured Text)はmarkdownやtextileと同様のプレーンテキストのマークアップ記法です。 一貫性を保持するために、CakePHPドキュメントに追加をする場合、以下のテキストのフォーマットと構造化をする方法のガイドラインに従うことが推奨されます。

行の長さ

テキストの行は80列でワードラップがかけられるべきです。 例外は長いURLとコードスニペットのみです。

見出しとセクション

セクションの見出しはテキストの長さ以上の区切り文字でタイトルにアンダーラインをつけることで作成されます。

• # はページタイトルを意味するのに使われます。
• = はページのセクションを意味するのに使われます。
• - はサブセクションを意味するのに使われます。
• ~ はサブ-サブセクションを意味するのに使われます。
• ^ はサブ-サブ-サブセクションを意味するのに使われます。

見出しは5レベルより深くネストしてはなりません。 また、空行で囲まれる必要があります。

段落(Paragraphs)

段落は単にテキストの塊で、全ての行に同じレベルのインデントがつけられます。 段落は1行以上の空行で区切られる必要があります。

インラインマークアップ

• 単一のアスタリスク: text 強調(斜体)、
• 二つのアスタリスク: text 強い強調(太文字)、
• バッククォート: text コード例。

もしアスタリスクやバッククォートがテキストが書かれている中に現れ、インラインマークアップの区切り文字に取り間違えられることがあるなら、バックスラッシュでエスケープする必要があります。

インラインマークアップは多少の制限があります:

• ネスト できない場合があります 。
• 中身は空白で開始・終了できないでしょう: * text* は間違いです。
• 中身は非単語文字で、周囲のテキストから分離されている必要があります。 これを回避するためにバックスラッシュでエスケープされた空白を使ってください: 一つの長い\ *太文字*\ 単語 。

リスト

リストマークアップはmarkdownに非常によく似ています。 順番なしのリストは単一のアスタリスクと空白から始まる行によって示されます。 順番がついたリストは同様に数字、または # で自動的なナンバリングがなされます:

* これは中黒(*bullet*)です
* これも同じです。しかしこの行は
  2行あります。

1. 一番目の行
2. 二番目の行

#. 自動的なナンバリング
#. は時間の節約をもたらします。

インデントされたリストも、セクションをインデントし、空行で区切ることによって作成できます:

* 一番目の行
* 二番目の行

    * 深くなってる
    * ワーオ！

* 最初のレベルに戻った。

定義リストは以下のようにして作成できます:

項目
    定義
CakePHP
    PHPのMVCフレームワーク

項目は1行以上にすることができませんが、定義は複数行にすることができ、全ての行は一貫したインデントをつける必要があります。

リンク

いくつかの用途に合った種類のリンクがあります。

外部リンク

外部のドキュメントへのリンクは以下のようにできます:

`外部リンク <http://example.com>`_

以上のものはhttp://example.comに向けてのリンクを生成します。

他のページへのリンク

:doc:

ドキュメントの他のページへ :doc: ロール(role)を使ってリンクします。 指定するドキュメントへ絶対パスまたは相対パス参照を用いてリンクできます。 .rst 拡張子は省く必要があります。 例えば、 :doc:`form` が core-helpers/html に現れたとすると、リンクは core-helpers/form を参照します。 もし参照が :doc:`/core-helpers` であったら、どこで使われるかを厭わずに、常に /core-helpers を参照します。

相互参照リンク

:ref:

:ref: ロールを使って任意のドキュメントに任意のタイトルを相互参照することができます。 リンクのラベルはドキュメント全体に渡って一意のものに向けられる必要があります。 クラスのメソッドのラベルを作る時は、リンクのラベルのフォーマットとして class-method を使うのがベストです。

ラベルの最も一般的な使い方は上記のタイトルです。例:

.. _ラベル名:

セクションの見出し
------------------

続きの内容..

他の場所で、 :ref:`ラベル名` を用いて上記のセクションを参照することができます。 リンクのテキストはリンクの先にあるタイトルになります。 また、 :ref:`リンクテキスト <ラベル名>` として自由にリンクのテキストを指定することができます。

クラスとその内容を記述する

CakePHPのドキュメントは phpdomain を用いてPHPのオブジェクトと構成物を記述するための独自のディレクティブを提供します。 適切な索引(index)と相互参照機能を与えるためにこのディレクティブとロールを必ず使う必要があります。

クラスと構成物を記述する

各々のディレクティブは索引と名前空間の索引のどちらか、または両方を生成します。

.. php:global:: name

このディレクティブは新規のPHPのグローバル変数を定義します。

.. php:function:: name(signature)

クラスに属さない新規のグローバル関数を定義します。

.. php:const:: name

このディレクティブは新規の定数を定義します。 これをclassディレクティブの中でネストして使うことにより、クラス定数を作成することもできます。

.. php:exception:: name

このディレクティブは現在の名前空間内で新規の例外(Exception)を定義します。 コンストラクタの引数を含める書き方もできます。

.. php:class:: name

クラスを記述します。 クラスに属するメソッド、属性、定数はこのディレクティブの本文の中にある必要があります:

.. php:class:: MyClass

    クラスの説明

   .. php:method:: method($argument)

   メソッドの説明

属性、メソッド、定数はネストする必要はありません。 これらは単にクラス定義の後につけることができます:

.. php:class:: MyClass

    クラスについての文

.. php:method:: methodName()

    メソッドについての文

参考

php:method, php:attr, php:const

.. php:method:: name(signature)

クラスのメソッドと、その引数、返り値、例外を記述します:

.. php:method:: instanceMethod($one, $two)

    :param string $one: 第一引数。
    :param string $two: 第二引数。
    :returns: なんらかの配列。
    :throws: InvalidArgumentException

   これはインスタンスメソッドです。

.. php:staticmethod:: ClassName::methodName(signature)

静的なメソッド、その引数、返り値、例外を記述します。 オプションは php:method を見てください。

.. php:attr:: name

クラスのプロパティ・属性を記述します。

相互参照

以下のロールはPHPのオブジェクトを参照し、適合するディレクティブがあればリンクが生成されます:

:php:func:

PHPの関数を参照します。

:php:global:

$ 接頭辞を持つグローバル変数を参照します。

:php:const:

グローバル定数、またはクラス定数のどちらかを参照します。 クラス定数はそのクラスが先に付けられる必要があります:

DateTimeは :php:const:`DateTime::ATOM` 定数を持ちます。

:php:class:

名前でクラスを参照します:

:php:class:`ClassName`

:php:meth:

クラスのメソッドを参照します。 このロールは両方の種類のメソッドをサポートします:

:php:meth:`DateTime::setDate`
:php:meth:`Classname::staticMethod`

:php:attr:

オブジェクトの属性を参照します:

:php:attr:`ClassName::$propertyName`

:php:exc:

例外を参照します。

ソースコード

段落の終わりの :: を用いて、リテラルコードブロックを生成します。 リテラルブロックはインデントされる必要があり、各段落のように単一の行で区切られる必要があります:

これは段落です::

    while ($i--) {
        doStuff()
    }

これは普通のテキストの再開です。

リテラルテキストは変更やフォーマットがされず、1レベル分のインデントが削除されたものが残ります。

注意と警告

重要なヒント、特別な注記、潜在的な危険を読者に知らせるためにしたいことがしばしばあります。 sphinxの警告(Admonitions)は、まさにそのために使われます。 警告には3つの種類があります。

• .. tip:: tipは面白い情報や重要な情報を文書化、または再反復するために使用されています。 ディレクティブの内容は完結した文章で書かれ、また全ての適切な句読点を含める必要があります。
• .. note:: noteは情報の特に重要なもののひとつを文書化するために使用されています。 ディレクティブの内容は完結した文章で書かれ、また全ての適切な句読点を含める必要があります。
• .. warning:: warningは潜在的な障害、またはセキュリティに関する情報を文書化するために使用されています。 ディレクティブの内容は完結した文章で書かれ、また全ての適切な句読点を含める必要があります。

全ての警告は同じようになります:

.. note::

    インデントされ空の行に挟まれます。
    段落と一緒です。

この文はnoteの一部ではありません。

サンプル

ちなみに

これは忘れがちで役に立つ一言です。

ノート

ここに注意を払う必要があります。

警告

危険に晒されるかもしれません。