文档¶

新的翻译语言¶

我们想要提供尽可能完整的翻译。然而，有时候某个翻译的文件没有更新。你应当总是认为 英文版本是最权威的版本。

如果你的语言没有出现在现有的语言中，请通过Github与我们联系，我们会考虑为该语言 创建一个目录骨架。下面的部分是你应当考虑首先翻译的，因为这些文件不经常变化：

• index.rst

• cakephp-overview.rst

• getting-started.rst

• installation.rst

• /installation folder

• /getting-started 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,...
  

对译者的提示¶

• 用要翻译的语言来进行浏览、编辑 - 否则你将无法看到哪些已经翻译了。

• 如果你选择的语言在本书中已经存在，请自行加入。

• 请使用 Informal Form 。

• 请将内容和标题一起翻译。

• 在提交一个更正之前，请先和英文版本的内容进行比较(如果你改正了一些东西，却没有 整合“上游”(upstream)的改动，你提交的东西将不会被接受)。

• 如果你要写一个英文术语，请把它放在 <em> 标签之内。比如， “asdf asdf Controller asdf”或者”asdf asdf Kontroller (Controller) asfd”， 请适为选用。

• 请不要提交不完整的翻译。

• 请不要编辑正在改动的部分。

• 对于标以重音符号的字符，请不要使用 html 字符实体 (html entities) 来表示，本书使用UTF-8。

• 请不要显著改变标记(HTML)或增加新的内容。

• 如果原始的内容遗漏了某些信息，请先提交(对原始内容的)更正。

每行的长度¶

每行文字应在80列处折行。唯一的例外是长的网址(URL)和代码片断。

标题和小节¶

小节的标题要在它的下一行用至少相同长度的标点符号来标识。

• # 用来标识网页标题。

• = 用于标识在一个页面中的小节。

• - 用于标识下一级的小节。

• ~ 用于标识再下一级的小节。

• ^ 用于标识更下一级的小节。

标题的嵌套深度不应超过5层。标题之前和之后都应留有一个空行。

段落¶

段落是简单的文本块，缩进在同一级别。段落之间应以一个以上的空行分隔。

内嵌(inline)标记¶

• 一个星号： 文字 为强调(斜体) 我们把它用于通常的标记／强调。

  • *text*。

• 两个星号： 文字 为高度强调(粗体) 我们把它用于工作目录，列表的标题，表格名称，但不包括下面的单词“table”。 We’ll use it for working directories, bullet list subject, table names and excluding the following word “table”.

  • **/config/Migrations**，**文章**，等等。

• 反引号： 文字 为代码样本 我们把它用于方法选项的名称，表格列的名称，对象名称，但不包括下面的单词“object”和方法／函数名称－－包括“()”。 We’ll use it for names of method options, names of table columns, object names, excluding the following word “object” and for method/function names – include “()”.

  • ``cascadeCallbacks``，``true``，``id``， ``PagesController``，``config()``，等等。

如果星号或反引号出现在文字中，并易与内嵌标记分隔符混淆，则必须用一个反斜杠转义。

内嵌标记有一些限制:

• 不可以 嵌套。

• 内容不可以以空格开始或结束: * 文本* 是错误的。

• 内容必须与周围的文字由非文字字符分隔，这可以使用反斜杠转义的空格来解决： 一个长的\ *粗体*\ 词汇。

列表¶

列表与 markdown 非常相似。无序列表以一个星号和一个空格开始。有序列表可以数字开始， 或以 # 进行自动编号:

* 这是一点
* 这也是。但这一点
  有两行。

1. 第一行
2. 第二行

#. 自动编号
#. 可以为你节省时间。

也可以创建缩进列表，只需缩进缩进列表那部分，并用一个空行分隔:

* 第一行
* 第二行

    * 缩进
    * 哇

* 回到第一层。

定义列表(Definition lists)，可以通过以下方式创建:

术语
    定义
CakePHP
    一个基于 PHP 的 MVC 框架

术语不可超过一行，但定义可以有多行并且所有行应当有同样的缩进。

链接¶

有几种类型的链接，每个都有自己的用途。

`外部链接 <http://example.com>`_

描述类和它们的内容¶

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, 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¶

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

防止 Sphinx 输出警告 Prevent Sphinx to Output Warnings ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

如果一个函数在多个文件中引用，Sphinx 就会输出警告。这可以很好地保证不会多次加入 一个函数，但是，有时候，你实际上就是要在两个或者多个文件中写同一个函数，例如 debug object 在 /development/debugging，也在 /core-libraries/global-constants-and-functions 中引用。在这种情况下，可以在 debug 函数之下增加 :noindex: 来防止警告。保证有一个引用 没有 :no-index:，这样就还可以使该函数被引用:

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

源代码¶

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

这是一个段落::

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

这又是正常的文字了。

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

注释和警告¶

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

• .. tip:: 提示用于说明或重申有趣或者重要的信息。应当使用完整的句子以及任何 适当的标点符号。

• .. note:: 注释是用来说明特别重要的信息。应当使用完整的句子以及任何适当的标 点符号。

• .. warning:: 警告用于描述潜在的障碍，或与安全有关的信息。应当使用完整的句 子以及任何适当的标点符号。

• .. versionadded:: X.Y.Z “增加的版本”告诫用来显示在一特定版本中增加的新功能， X.Y.Z 就是新增提到的功能的版本。

• .. deprecated:: X.Y.Z 与“增加的版本”告诫相反，“作废”告诫用来告知作废的功能， X.Y.Z 就是提到的功能作废的版本。

所有告诫都是相同的:

.. note::

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

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