文档

给文档做贡献是很简单的。这些文件都托管在 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:function:: name(signature)

定义一个新的处于类之外的函数。

.. php:const:: name

这个指令声明一个新的 PHP 常量,也可以在一个类的指令之内使用它来创建类的常量。

.. php:exception:: name

这个指令在当前命名空间内声明一个新的 PHP 异常。其签名可以包括构造函数的参数。

.. php:class:: name

描述了一个类。属于该类的方法、属性和常量应该处于这个指令之内:

.. php:class:: MyClass

    类的说明

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

   方法的说明

属性、方法和常量不需要嵌套。他们可以直接位于类的声明之后:

.. php:class:: MyClass

    关于类的文字

.. php:method:: methodName()

    关于方法的文字
.. 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

描述一个类的属性(property/attribute)。

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:

交叉引用

以下角色指向 PHP 对象,如果有匹配的指令,就会生成链接:

:php:func:

指向一个PHP函数。

:php:global:

指向一个名称以 $ 开始的全局变量。

:php:const:

指向一个全局常量、或类的常量。类的常量应当以所属类为前缀。

DateTime 有一个 DateTime::ATOM 常量。
:php:class:

指向一个以名称标识的类:

:php:class:`ClassName`
:php:meth:

指向一个类的方法,该角色支持两种方法:

:php:meth:`DateTime::setDate`
:php:meth:`类名::静态方法`
:php:attr:

指向一个对象的属性:

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

指向一个异常。

源代码

一个段落以 :: 结束,就可以创建代码块。该段落必须缩进,且象所有段落一样,须以 单个空行分隔:

这是一个段落::

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

这又是正常的文字了。

代码的文字不会被改动或格式化,除非取消该级别的缩进。

注释和警告

有很多时候,你会想告诉读者一个重要的提示、特别的说明或者可能的危险。sphinx 中的告 诫(Admonition)正是为了这个目的。有三种类型的告诫。

  • .. tip:: 提示用于说明或重申有趣或者重要的信息。应当使用完整的句子以及任何适 当的标点符号。
  • .. note:: 注释是用来说明特别重要的信息。应当使用完整的句子以及任何适当的标 点符号。
  • .. warning:: 警告用于描述潜在的障碍,或与安全有关的信息。应当使用完整的句子 以及任何适当的标点符号。

所有告诫都是相同的:

.. note::

    缩进,并且前后都应留有一个空行,就象普通段落一样。

此文字不是注释的一部分。

示例

小技巧

这是一条有用的信息,你可能忘记了。

注解

你应当注意这里。

警告

它可能有危险。