ドキュメント

ドキュメントへの貢献の方法はシンプルです。ファイルは https://github.com/cakephp/docs にホストされています。自由にリポジトリーをフォークして、変更・改善・翻訳を追加し、プルリクエストを発行してください。またファイルをダウンロードせず、 GitHub を使ってオンラインでドキュメントを編集することもできます。どのページにも存在している「Improve this Doc」ボタンを押すことで、 GitHub 上にあるそのページのオンラインエディターに飛ぶことができます。

CakePHP ドキュメントは、プルリクエストがマージされるごとに継続的インテグレーションが行われ、デプロイされます。

翻訳

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

新たに翻訳する言語

できるだけ完全な翻訳を提供したいのですが、翻訳ファイルが最新になっていない部分もありえます。常に英語バージョンを正のバージョンと考えてください。

もし、あなたの言語が現在の言語の中に無いなら、我々に Github 経由で連絡を頂ければ、我々はスケルトンフォルダーの作成を考えます。以下のセクションは頻繁に書き換わらないファイルなので翻訳を検討するにはもっとも適しています:

index.rst
intro.rst
quickstart.rst
installation.rst
/intro folder
/tutorials-and-examples folder

ドキュメント管理者へのリマインド

すべての言語フォルダーの構造は英語フォルダーの構造のミラーであるべきです。もし英語版の構造が変わったら、我々はそれらの変更を他の言語にも適用します。

たとえば、新しい英語のファイルが en/file.rst に作成されたら、我々は次のようにします:

他のすべての言語の中にそのファイルを追加します : fr/file.rst, zh/file.rst, ...

中身を削除します。ただし、 title 、 meta 情報、 toc-tree 要素は残しておきます。次の記述は誰も翻訳していないファイルに記載されるものです。 :

text

File Title
##########

.. note::
    The documentation is not currently supported in XX language for this
    page.

    Please feel free to send us a pull request on
    `Github <https://github.com/cakephp/docs>`_ or use the **Improve This Doc**
    button to directly propose your changes.

    You can refer to the English version in the select top menu to have
    information about this page's topic.

// If toc-tree elements are in the English version
.. toctree::
    :maxdepth: 1

    one-toc-file
    other-toc-file

.. meta::
    :title lang=xx: File Title
    :keywords lang=xx: title, description,...

翻訳者tips

翻訳先の言語のページを閲覧・編集してください。そうしなければ、翻訳済みのものは見えません。
選択した言語が book 上にすでに存在しているなら、遠慮無くその先に飛び込んでください。
堅苦しくない文体を使ってください。
タイトルと内容を同時に翻訳してください。
修正を投稿する前に、英語版との比較を行うようにしてください（何か修正しても、 'upstream' の変更が含まれていないなら、あなたの投稿は受け入れられません）。
用語を英語で書く必要があるなら、 <em> タグで囲んでください。例えば、「asdf asdf Controller asdf」や「asdf asdf Kontroller (Controller) asfd」などです。
一部だけ翻訳して投稿しないでください。
保留されている項目があるセクションは編集しないでください。
アクセント文字のために HTML エンティティーを使用しないでください。この book は UTF-8 を使っています。
マークアップ (HTML) の変更や新しいコンテンツを絶対に変更しないでください。
元のコンテンツに不備がある場合は、まずそれを編集するようにしてください。

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

新しい CakePHP のドキュメントは ReST 形式で書かれています。 ReST (Re Structured Text) は markdown や textile に似たプレーンテキストのマークアップ記法です。一貫性を保持するために、CakePHP ドキュメントに追加をする際には、自分のテキストのフォーマットと構造をこのガイドラインに合わせてください。

行の長さ

テキストの行は半角 80 列を基準に改行してください。例外は長い URL とコードスニペットのみです。

見出しとセクション

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

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

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

段落(Paragraphs)

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

インラインマークアップ

単一のアスタリスク: text 強調(斜体) 我々はこれを一般的なハイライト/強調に使います。
- *text* 。
二つのアスタリスク: text 強い強調(太文字) 我々はこれを作業ディレクトリー、箇条書きリストのタイトル、テーブル名（後に続く単語 "table" は含めません）に使います。
- **/config/Migrations** 、 **articles** など。
２つのバッククォート: text コード例。我々はこれをメソッドのオプション名、テーブルの列名、オブジェクト名（後に続く単語 "object" は含めません）、メソッド/関数名（ "()" を含めます）に使います。
- cascadeCallbacks 、 true 、 id 、 PagesController 、 config() など。

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

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

ネスト できません 。
マークアップ対象の最初や最後が空白ではいけません: * text* は間違いです。
マークアップ対象は非単語文字（訳注:空白等）で囲まれることで、それ以外と区別されていなければなりません。単語を分けたくない場合はバックスラッシュで空白をエスケープしてください: 一続きの長い\ *太字部分*\ を含む単語 。

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

text

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

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

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

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

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

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

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

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

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

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

リンク

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

外部リンク

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

text

`php.net への外部リンク <https://php.net>`_

以上のものは次のようにリンクします: php.net への外部リンク

他のページへのリンク

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

相互参照リンク

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

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

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

Sphinx が出力する警告を防ぐ

Sphinx は toc-tree 内に参照されないファイルがあると警告を出力します。これは、すべてのファイルが正しいリンクを持っていることを確認する良い方法ではありますが、ファイルへのリンクを挿入する必要がないときもありえます。たとえば、 epub-contents と pdf-contents などがそうです。これらのケースでは、ファイルの先頭に :orphan: を加えることで、このファイルが toc-tree にいないという警告を抑えることができます。

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

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

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

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

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

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

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

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

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

    クラスの説明

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

   メソッドの説明
1
2
3
4
5
6
7
属性、メソッド、定数はネストする必要はありません。これらは単にクラス定義の後につけることができます。 :
text
.. php:class:: MyClass

    クラスについての文

.. php:method:: methodName()

    メソッドについての文
1
2
3
4
5
6
7
php:method, php:attr, php:const

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

text

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

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

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

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

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

Sphinx が出力する警告を防ぐ

Sphinx は関数が複数のファイルから参照されていると警告を出力します。これは、関数を２度追加していないことを確認する良い方法ではありますが、実際には複数回にわたって関数を書きたいときもありえます。たとえば、 debug object が /development/debugging と /core-libraries/global-constants-and-functions から参照されます。このケースでは、debug 関数の下に :noindex: を加えることで、警告を抑えることができます。その関数が参照されるために :no-index: の無い参照を１つだけを残して下さい。 :

php

.. php:function:: debug(mixed $var, boolean $showHtml = null, $showFrom = true)
    :noindex:

相互参照

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

PHP の関数を参照します。

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

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

名前でクラスを参照します。 :
:php:class:`ClassName`

クラスのメソッドを参照します。このロールは両方の種類のメソッドをサポートします。 :
php
:php:meth:`DateTime::setDate`
:php:meth:`Classname::staticMethod`
1
2

オブジェクトの属性を参照します。 :
text
:php:attr:`ClassName::$propertyName`
1

例外を参照します。

ソースコード

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

text

これは段落です。 ::

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

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

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

注意と警告

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

.. tip:: tip は面白い情報や重要な情報を文書化、または再反復するために使用されています。ディレクティブの内容は完結した文章で書かれ、また全ての適切な句読点を含める必要があります。
.. note:: note は情報の特に重要なもののひとつを文書化するために使用されています。ディレクティブの内容は完結した文章で書かれ、また全ての適切な句読点を含める必要があります。
.. warning:: warning は潜在的な障害、またはセキュリティに関する情報を文書化するために使用されています。ディレクティブの内容は完結した文章で書かれ、また全ての適切な句読点を含める必要があります。
.. versionadded:: X.Y.Z "バージョン追加" 勧告は特定のバージョンで追加された新機能特有の注記を表示するために使われます。 X.Y.Z はその機能が追加されたバージョンです。
.. deprecated:: X.Y.Z "バージョン追加" 勧告とは反対に、 "撤廃" 勧告は、廃止される機能を通知するために使われます。 X.Y.Z はその機能が撤廃されるバージョンです。

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

text

.. note::

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

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

サンプル

TIP

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

NOTE

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

WARNING

危ないかもしれません。

Added in version 2.6.3

すごい機能がバージョン 2.6.3 で追加されました。

Deprecated in version 2.6.3

この古い機能はバージョン 2.6.3 で撤廃されます。

ドキュメント ​

翻訳 ​

新たに翻訳する言語 ​

ドキュメント管理者へのリマインド ​

翻訳者tips ​

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

行の長さ ​

見出しとセクション ​

段落(Paragraphs) ​

インラインマークアップ ​

リスト ​

リンク ​

外部リンク ​

他のページへのリンク ​

相互参照リンク ​

Sphinx が出力する警告を防ぐ ​

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

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

Sphinx が出力する警告を防ぐ ​

相互参照 ​

ソースコード ​

注意と警告 ​

サンプル ​

ドキュメント

翻訳

新たに翻訳する言語

ドキュメント管理者へのリマインド

翻訳者tips

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

行の長さ

見出しとセクション

段落(Paragraphs)

インラインマークアップ

リスト

リンク

外部リンク

他のページへのリンク

相互参照リンク

Sphinx が出力する警告を防ぐ

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

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

Sphinx が出力する警告を防ぐ

相互参照

ソースコード

注意と警告

サンプル