发布于 2015-08-27 16:45:45 | 151 次阅读 | 评论: 0 | 来源: 网络整理
Symfony文档使用 reStructuredText 作为其标记语言，使用 Sphinx 来生成可读文档，如HTML，PDF等。
reStructuredText 是与Markdown相似的纯文本标记语言，但其语法比Markdown严格的多。如果你不了解reStructuredText，花些时间来通过阅读已有的 Symfony documentation 文档，进而熟悉它的语法格式。
如果你想更深入的掌握reStructuredText，请阅读 reStructuredText Primer 指南，以及 reStructuredText Reference 参考。
警告
如果你很熟悉Markdown，请注意reStructuredText不同的地方：
列表必须开始于行首（不可有缩进）
内嵌代码块使用两个反引号（backquote/backtick） （``像这样``）
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``来演示同一功能代码的不同语言实现，如（``PHP，YAML 和 XML）：
.. configuration-block::
.. code-block:: yaml
# Configuration in YAML
.. code-block:: xml
<!-- Configuration in XML -->
.. code-block:: php
// Configuration in PHP
上面的reST会被渲染成如下这种形式：
# Configuration in YAML
<!-- Configuration in XML -->
// 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注释 |
最为通用的链接为 文档内部链接，用于指向其它文档页：
:doc:`/absolute/path/to/page`
路径中的文档页名无需加上扩展名（.rst）：
:doc:`/book/controller`
:doc:`/components/event_dispatcher/introduction`
:doc:`/cookbook/configuration/environments`
链接的名称将自动采用所指向文档页的标题，但如果你想修改链接名称，可采用如下替代语法：
:doc:`Spooling Email </cookbook/email/spool>`
注解
尽管在技术上采用相对路径是可行的，但请尽量采用绝对路径来指向文档页，因为使用相对路径可能会导致生成的PDF文档无法被正确索引：
:doc:`controller`
:doc:`event_dispatcher/introduction`
:doc:`environments`
链接到API 必须指定所链接资源的类型（namespace，class 或 method）：
:namespace:`SymfonyComponentBrowserKit`
:class:`SymfonyComponentRoutingMatcherApacheUrlMatcher`
:method:`SymfonyComponentHttpKernelBundleBundle::build`
链接到PHP文档 使用相似的语法：
:phpclass:`SimpleXMLElement`
:phpmethod:`DateTime::createFromFormat`
:phpfunction:`iterator_to_array`
如果你正在编写与新特性相关或在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 文档分支中去除。