文档格式

Symfony文档使用 reStructuredText 作为其标记语言,使用 Sphinx 来生成可读文档,如HTML,PDF等。

reStructuredText

reStructuredText 是与Markdown相似的纯文本标记语言,但其语法比Markdown严格的多。如果你不了解reStructuredText,花些时间来通过阅读已有的 Symfony documentation 文档,进而熟悉它的语法格式。

如果你想更深入的掌握reStructuredText,请阅读 reStructuredText Primer 指南,以及 reStructuredText Reference 参考。

警告

如果你很熟悉Markdown,请注意reStructuredText不同的地方:

  • 列表必须开始于行首(不可有缩进)

  • 内嵌代码块使用两个反引号(backquote/backtick) (``像这样``

Sphinx

Sphinx 是一个自动化构建系统,它提供从reStructuredText文件生成文档的工具。它会在你的目录下创建文件夹用于将 `text roles`_ 解析成标准reST标记。了解更多请阅读 Sphinx Markup Constructs

语法高亮

PHP在所有代码块中默认高亮。但你可以使用 code-block 指令来修改当前需要高亮的语言:

.. code-block:: yaml

    { foo: bar, bar: { foo: bar, bar: baz } }

注解

除了所有主流编程语言外,语法高亮器还支持所有其它的标记与配置语言。你可以查看支持的语言: supported languages

组合代码块

每次你想在文档中举例时,可以使用 configuration-block``来演示同一功能代码的不同语言实现,如(``PHPYAMLXML):

.. configuration-block::

    .. code-block:: yaml

        # Configuration in YAML

    .. code-block:: xml

        <!-- Configuration in XML -->

    .. code-block:: php

        // Configuration in PHP

上面的reST会被渲染成如下这种形式:

  • YAML
    # Configuration in YAML
    
  • XML
    <!-- Configuration in XML -->
    
  • PHP
    // Configuration in PHP
    

当前支持的格式有:

标记格式

渲染形式

html HTML
xml XML
php PHP
yaml YAML
jinja

纯Twig

html+jinja

Twig混合HTML

html+php

PHP混合HTML

ini INI
php-annotations

PHP Annotations注释

新特性与变更

如果你正在编写与新特性相关或在Symfony中已经实现的变更时,你应该添加上版本标签``.. versionadded:: 2.X`` ,并附上一个简介:

.. versionadded:: 2.3
    The ``askHiddenResponse`` method was introduced in Symfony 2.3.

You can also ask a question and hide the response. This is particularly [...]

如果你正在描述一个变更,最好 简单地 描述一下什么发生了改变:

.. versionadded:: 2.3
    The ``include()`` function is a new Twig feature that's available in
    Symfony 2.3. Prior, the ``{% include %}`` tag was used.

随着Symfony不断发布新的版本(如 2.4,2.5,等),新的文档分支也从 master 中创建出来,在此时所有过期的 versionadded 标签将被去除。例如,假设Symfony 2.5版本今天发布,并且2.2版本退出支持,那么2.2版本 versionadded 标签将被在新的 2.5 文档分支中去除。

测试文档

当你提交了新内容或新修改到文档库,你的提交会被自动检测是否含有语法错误。

不过,如果你希望在提交你的更改前,首先在你自己的电脑上进行预览测试,你需要:

  • 安装 Sphinx

  • 使用git submodules来安装Sphinx扩展: $ git submodule update --init

  • 在终端执行 make html,生成的HTML文档存储在 build/ 文件夹下