给文档做贡献是很简单的。这些文件都托管在
https://github.com/cakephp/docs
。请自行
复制(
fork
)代码仓库，加入你的更改/改进/翻译，然后发出拉取请求来提交你的改动。你
甚至可以在 GitHub 上在线地编辑文档，而完全不用下载文件–在任何页面上的”Improve
this Doc”按键将会引导你进入该页面的 GitHub 在线编辑器。
发邮件给文档小组(docs at cakephp dot org)，或者通过 IRC(freenode上的#cakephp)，来
讨论任何你想参与的翻译工作。
关于翻译的一些忠告:
用要翻译的语言来进行浏览、编辑 - 否则你将无法看到哪些已经翻译了。
如果你选择的语言在本书中已经存在，请自行加入。
请使用
Informal Form
。
请将内容和标题一起翻译。
在提交一个更正之前，请先和英文版本的内容进行比较(如果你改正了一些东西，却没有整
合“上游”(
upstream
)的改动，你提交的东西将不会被接受)。
如果你要写一个英文术语，请把它放在
<em>
标签之内。比如，
“asdf asdf
Controller
asdf”或者”asdf asdf Kontroller (
Controller
) asfd”，请
适为选用。
请不要提交不完整的翻译。
请不要编辑正在改动的部分。
对于标以重音符号的字符，请不要使用
html 字符实体
(
html entities
) 来表示，本书使用UTF-8。
请不要显著改变标记(HTML)或增加新的内容。
如果原始的内容遗漏了某些信息，请先提交(对原始内容的)更正。
文档格式指南
这份新的 CakePHP 文档是以
ReST formatted text
格式写的。
ReST (Re Structured Text)是与 markdown 或者 textile 类似的纯文本标记语法。在为
CakePHP 的文档做出贡献时，为了保持一致性，建议你遵循下面的准则，来你格式化和组织
你的文字。
每行的长度
每行文字应在80列处折行。唯一的例外是长的网址和代码片断。
标题和小节
小节的标题要在它的下一行用至少相同长度的标点符号来标识。
#
用来标识网页标题。
=
用于标识在一个页面中的小节。
-
用于标识下一级的小节。
~
用于标识再下一级的小节。
^
用于标识更下一级的小节。
标题的嵌套深度不应超过5层。标题之前和之后都应留有一个空行。
段落是简单的文本块，缩进在同一级别。段落之间应以一个以上的空行分隔。
内嵌(
inline
)标记
一个星号：
文字
为强调(斜体)
*text*
两个星号：
文字
为高度强调(粗体)
**text**
反引号：
文字
为代码样本
``text``
如果星号或反引号出现在文字中，并易与内嵌标记分隔符混淆，则必须用一个反斜杠转义。
内嵌标记有一些限制:
不可以
嵌套。
内容不可以以空格开始或结束:
*
文本*
是错误的。
内容必须与周围的文字由非文字字符分隔，这可以使用反斜杠转义的空格来解决：
一个长的\
*粗体*\
词汇
。
列表与 markdown 非常相似。无序列表以一个星号和一个空格开始。有序列表可以数字开始，
或以
#
进行自动编号:
* 这是一点
* 这也是。但这一点
1. 第一行
2. 第二行
#. 自动编号
#. 可以为你节省时间。
也可以创建缩进列表，只需缩进缩进列表那部分，并用一个空行分隔:
* 第一行
* 第二行
* 缩进
* 回到第一层。
定义列表(Definition lists)，可以通过以下方式创建:
CakePHP
一个基于 PHP 的 MVC 框架
术语不可超过一行，但定义可以有多行并且所有行应当有同样的缩进。
有几种类型的链接，每个都有自己的用途。
外部链接
链接到外部文件如下:
`外部链接 <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:`链接文字 <标签名称>` 的方式来提供自定义的链接文字。
Prevent Sphinx to Output Warnings
Sphinx will output warnings if a file is not referenced in a toc-tree. It’s
a great way to ensure that all files have a link directed to them, but
sometimes, you don’t need to insert a link for a file, eg. for our
epub-contents and pdf-contents files. In those cases, you can add
:orphan: at the top of the file, to suppress warnings that the file is not
in the toc-tree.
描述类和它们的内容
CakePHP 文档使用 phpdomain
提供自定义指令描述 PHP 对象和结构。我们必须使用这些指令和角色，才能保证正确的索引
和交叉引用。
描述类及其组成
每个指令生成索引，或命名空间索引。
.. php:global:: name
这个指令声明一个新的PHP全局变量。
.. php:method:: name(signature)
描述一个类的方法，其参数、返回值以及异常:
.. php:method:: instanceMethod($one, $two)
:param string $one: 第一个参数.
:param string $two: 第二个参数.
:returns: 一个数组。
:throws: InvalidArgumentException
这是一个实例方法。
Prevent Sphinx to Output Warnings
Sphinx will output warnings if a function is referenced in multiple files. It’s
a great way to ensure that you did not add a function two times, but
sometimes, you actually want to write a function in two or more files, eg.
debug object is referenced in /development/debugging and in
/core-libraries/global-constants-and-functions. In this case, you can add
:noindex: under the function debug to suppress warnings. Keep only
one reference without :no-index: to still have the function referenced:
.. php:function:: debug(mixed $var, boolean $showHtml = null, $showFrom = true)
:noindex:
.. tip:: 提示用于说明或重申有趣或者重要的信息。应当使用完整的句子以及任何适
当的标点符号。
.. note:: 注释是用来说明特别重要的信息。应当使用完整的句子以及任何适当的标
.. warning:: 警告用于描述潜在的障碍，或与安全有关的信息。应当使用完整的句子
以及任何适当的标点符号。
所有告诫都是相同的:
.. note::
缩进，并且前后都应留有一个空行，就象普通段落一样。
此文字不是注释的一部分。
这是一条有用的信息，你可能忘记了。
你应当注意这里。
它可能有危险。
