ドキュメント¶

新たに翻訳する言語¶

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

もし、あなたの言語が現在の言語の中に無いなら、 我々に 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 要素は残しておきます。 次の記述は誰も翻訳していないファイルに記載されるものです。

  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 上にすでに存在しているなら、遠慮無くその先に飛び込んでください。

• 堅苦しくない文体を使ってください。

• エンジニアに通じる言葉 を使ってください。たとえば「Assert」という単語は直訳すると「主張」「表明」という意味になりますが、エンジニアに対しては「アサート」とすべきです。

• タイトルと内容を同時に翻訳してください。

• 修正を投稿する前に、英語版との比較を行うようにしてください （何か修正しても、 'upstream' の変更が含まれていないなら、あなたの投稿は受け入れられません）。

• 用語を英語で書く必要があるなら、 <em> タグで囲んでください。 例えば、「asdf asdf Controller asdf」 や 「asdf asdf Kontroller (Controller) asfd」 などです。

• 一部だけ翻訳して投稿しないでください。

• 保留されている項目があるセクションは編集しないでください。

• アクセント文字のために HTML エンティティー を使用しないでください。 この book は UTF-8 を使っています。

• マークアップ (HTML) の変更や新しいコンテンツを絶対に変更しないでください。

• 元のコンテンツに不備がある場合は、まずそれを編集するようにしてください。

行の長さ¶

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

見出しとセクション¶

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

• # はページタイトルを示すのに使われます。

• = はページ内のセクションを意味するのに使われます。

• - はサブセクションを意味するのに使われます。

• ~ はサブ-サブセクションを意味するのに使われます。

• ^ はサブ-サブ-サブセクションを意味するのに使われます。

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

段落(Paragraphs)¶

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

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

• 単一のアスタリスク: text 強調(斜体) 我々はこれを一般的なハイライト/強調に使います。

  • *text* 。

• 二つのアスタリスク: text 強い強調(太文字) 我々はこれを作業ディレクトリー、箇条書きリストのタイトル、 テーブル名（後に続く単語 "table" は含めません）に使います。

  • **/config/Migrations** 、 **articles** など。

• ２つのバッククォート: text コード例。 我々はこれをメソッドのオプション名、テーブルの列名、 オブジェクト名（後に続く単語 "object" は含めません）、 メソッド/関数名（ "()" を含めます ）に使います。

  • ``cascadeCallbacks`` 、 ``true`` 、 ``id`` 、 ``PagesController`` 、 ``config()`` など。

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

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

• ネスト できません 。

• マークアップ対象の最初や最後が空白ではいけません: * text* は間違いです。

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

リスト¶

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

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

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

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

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

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

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

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

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

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

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

リンク¶

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

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

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

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:function:: debug(mixed $var, boolean $showHtml = null, $showFrom = true)
    :noindex:

ソースコード¶

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

これは段落です。 ::

    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 はその機能が撤廃されるバージョンです。

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

.. note::

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

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