文档标准

Sphinx¶

• 如下的字符被用来代表文档中标题的大小：一级标题 =，二级标题 -，三级标题 ~，四级标题 .，五级标题(段落) "

• 每行应在第72-78个字符左右的位置断行

• 短码（shorthand） :: 等同于 .. code-block:: php ，用于开始一个PHP代码块（阅读 the Sphinx documentation 来了解你应在什么时候使用短码)

• Inline hyperlinks are not used. Separate the link and their target definition, which you add on the bottom of the page;

• 标记应在一行内开始并结束

Example
=======

When you are working on the docs, you should follow the
`Symfony Documentation`_ standards.

Level 2
-------

A PHP example would be::

    echo 'Hello World';

Level 3
~~~~~~~

.. code-block:: php

    echo 'You cannot use the :: shortcut here';

.. _`Symfony Documentation`: http://symfony.com/doc

内嵌代码¶

• 代码应遵循 Symfony代码标准 以及 Twig Coding Standards

• The code examples should look real for a web application context. Avoid abstract or trivial examples (foo, bar, demo, etc.);
• The code should follow the Symfony Best Practices. Unless the example requires a custom bundle, make sure to always use the AppBundle bundle to store your code;
• Use Acme when the code requires a vendor name;

• 一行代码请不要超过85个字符

• 当你想要折叠/省略一行或多行代码时，在折叠的位置请将 ... 加入注释中： // ... (php)，# ... (yaml/bash)，{# ... #} (twig)， <!-- ... --> (xml/html)，; ... (ini)，... (text)

• 当你只想折叠/省略一行代码的一部分时，直接用 ... 替换即可

• 描述折叠/省略的代码（可选）：

  • 一行或多行：在 ... 后加入描述，

  • 行的一部分：将描述放于行前

• 如果需要，PHP代码应从命名空间开始

• 当引用它类时，确保 use 语句在代码块最上方。无需在每个例子中加入 所有 use 语句，

• 只加入当前所需的部分如果需要，一个 codeblock 应当开始于一个注释，当中加入该代码块所在的文件名以及文件路径，在这个注释后也不要加空行，除非下一行也是一行注释

• 将 $ 插入在bash代码块的每行行首

// src/Foo/Bar.php
namespace Foo;

use AcmeDemoCat;
// ...

class Bar
{
    // ...

    public function foo($bar)
    {
        // set foo with a value of bar
        $foo = ...;

        $cat = new Cat($foo);

        // ... check if $bar has the correct value

        return $cat->baz($bar, ...);
    }
}

文件与目录¶

• 当引用目录时，在目录名称后加上一个/，以避免与文件名混淆（如 “execute the console script located at the app/ 目录”）。

• 当显式的引用外部文件时，加上文件扩展名（如 “XML files use the .xml extension”）。

• 当需要打印Symfony文件/目录的层级关系时，使用 your-project/ 作为根目录，如：

  your-project/
  ├─ app/
  ├─ src/
  ├─ vendor/
  └─ ...
  

English Language Standards（英语标准）¶

Symfony documentation uses the United States English dialect, commonly called American English. The American English Oxford Dictionary is used as the vocabulary reference.

In addition, documentation follows these rules:

• Section titles: use a variant of the title case, where the first word is always capitalized and all other words are capitalized, except for the closed-class words (read Wikipedia article about headings and titles).

  E.g.: The Vitamins are in my Fresh California Raisins

• Punctuation: avoid the use of Serial (Oxford) Commas;

• Pronouns: avoid the use of nosism and always use you instead of we. (i.e. avoid the first person point of view: use the second instead);

• Gender-neutral language: when referencing a hypothetical person, such as “a user with a session cookie”, use gender-neutral pronouns (they/their/them). For example, instead of:

  • he or she, use they
  • him or her, use them
  • his or her, use their
  • his or hers, use theirs
  • himself or herself, use themselves