文档标准

Sphinx

• 以下字符被选择用于不同的标题级别：1 级是 = (等号)，2 级是 - (破折号)，3 级是 ~ (波浪号)，4 级是 . (点) 和 5 级是 " (双引号)；
• 每行应在大约超过第 72 个字符的第一个单词后断开（因此大多数行的长度最终为 72-78 个字符）；
• 除非 :: 简写导致标记单独成行（请阅读 Sphinx 文档 以了解何时应使用简写），否则 :: 简写优先于 .. code-block:: php 来开始 PHP 代码块；
• 不使用内联超链接。分隔链接及其目标定义，您可以在页面底部添加它们；
• 内联标记应与开始字符串在同一行关闭；

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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.ac.cn/doc

代码示例

• 代码遵循 Symfony 编码标准以及 Twig 编码标准；
• 代码示例应该在 Web 应用程序上下文中看起来真实。避免抽象或琐碎的例子（foo、bar、demo 等）；
• 代码应遵循 Symfony 最佳实践。
• 当代码需要供应商名称时，请使用 Acme；
• 当需要额外的域名时，使用 example.com 作为示例 URL 的域名，以及 example.org 和 example.net。所有这些域名都由 IANA 保留。
• 为了避免代码块上的水平滚动，我们更倾向于在行超过 85 个字符时正确断行；
• 当您折叠一行或多行代码时，在折叠点放置 ... 在注释中。这些注释是：// ... (PHP)、# ... (Yaml/bash)、{# ... #} (Twig)、<!-- ... --> (XML/HTML)、; ... (INI)、... (文本)；
• 当您折叠行的一部分时，例如变量值，请在折叠位置放置 ...（无注释）；

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

  • 如果您折叠多行：折叠的描述可以放在 ... 之后；
  • 如果您仅折叠行的一部分：描述可以放在行之前；
• 如果对读者有用，PHP 代码示例应以命名空间声明开头；
• 当引用类时，请务必在代码块顶部显示 use 语句。您无需在每个示例中显示所有 use 语句，只需显示代码块中实际使用的内容即可；
• 如果有用，codeblock 应以包含代码块中文件名的注释开头。请勿在此注释后放置空行，除非下一行也是注释；
• 您应该在每个 bash 行前面放一个 $。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

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

use Acme\Demo\Cat;
// ...

class Bar
{
    // ...

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

        $cat = new Cat($foo);

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

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

文件和目录

• 当引用目录时，始终添加尾部斜杠以避免与常规文件混淆（例如，“执行位于 bin/ 目录中的 console 脚本”）。
• 当显式引用文件扩展名时，您应该为每个扩展名包含前导点（例如，“XML 文件使用 .xml 扩展名”）。

• 当您列出 Symfony 文件/目录层次结构时，请使用 your-project/ 作为顶级目录。例如

  1
  2
  3
  4
  5

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

图片和图表

• 图表必须遵守 Symfony 文档风格。这些图表是使用 Dia 应用程序创建的，以确保每个人都可以编辑它们。请参阅 GitHub 上的 README 以获取有关如何创建它们的说明。

• 所有图片和图表都必须包含 alt 描述

  • 保持描述简洁，不要重复图中周围的信息；
  • 在图表周围的文本中描述复杂图表，而不是在 alt 描述中。在这些情况下，alt 描述必须描述可以在哪里找到更长的描述（例如，“这些元素在接下来的章节中进一步描述”）；
  • 描述以大写字母开头，以句点结尾；
  • 不要以“...的屏幕截图”、“...的图表”等开头，除非需要知道确切的类型（例如，特定的图表类型）。

1
2
3
4
5
6
7
8

.. image:: /_images/example-screenshot.png
    :alt: Some concise description of the screenshot.

.. raw:: html

    <object data="_images/example-diagram.svg" type="image/svg+xml"
        alt="Some concise description."
    ></object>

英语语言标准

Symfony 文档使用美国英语方言，通常称为 美式英语。《美国英语牛津词典》用作词汇参考。

此外，文档遵循以下规则

• 章节标题：使用标题大小写的变体，其中第一个单词始终大写，所有其他单词也都大写，但封闭类词除外（阅读 Wikipedia 上关于标题和标题的文章）。

  例如：The Vitamins are in my Fresh California Raisins

• 标点符号：避免使用序列（牛津）逗号；
• 代词：避免使用自大语态，并始终使用 you 而不是 we。（即，避免第一人称视角：而使用第二人称）；

• 性别中立语言：当引用假设的人时，例如“具有会话 Cookie 的用户”，请使用性别中立的代词 (they/their/them)。例如，代替

  • 他或她，使用 they
  • 他或她，使用 them
  • 他或她的，使用 their
  • 他的或她的，使用 theirs
  • 他自己或她自己，使用 themselves

• 避免轻视的词语：对于记录文档的人来说，看起来“明显”或“简单”的事情，对于读者来说可能恰恰相反。为了确保每个人在阅读文档时都感到舒适，请尽量避免使用以下词语

  • 基本上
  • 显然
  • 容易/轻易地
  • 仅仅
  • 逻辑上
  • 仅仅
  • 明显地
  • 当然
  • 快速/快速地
  • 简单地
  • 微不足道
• 允许使用缩略形式：例如，您可以写 you would 以及 you'd，it is 以及 it's 等。