文档格式

编辑此页

Symfony 文档使用 reStructuredText 作为其标记语言，并使用 Sphinx 来生成最终用户可读的文档格式，例如 HTML 和 PDF。

reStructuredText

reStructuredText 是一种纯文本标记语法，类似于 Markdown，但在语法上更加严格。如果您是 reStructuredText 的新手，请花一些时间阅读现有的 Symfony 文档 源代码，熟悉这种格式。

如果您想了解更多关于这种格式的信息，请查看 reStructuredText Primer 教程和 reStructuredText Reference。

警告

如果您熟悉 Markdown，请注意，有些地方非常相似但又不同

  • 列表从行首开始（不允许缩进）；
  • 内联代码块使用双反引号 (``like this``)。

Sphinx

Sphinx 是一个构建系统，提供工具来从 reStructuredText 文档创建文档。因此，它向标准的 reStructuredText 标记添加了新的指令和解释文本角色。阅读更多关于 Sphinx 标记结构 的信息。

语法高亮

PHP 是应用于所有代码块的默认语法高亮器。您可以使用 code-block 指令来更改它

1
2
3
.. code-block:: yaml

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

注意

除了所有主要的编程语言外，语法高亮器还支持各种标记和配置语言。在语法高亮器网站上查看 受支持语言 的列表。

配置块

无论何时您包含配置示例，请使用 configuration-block 指令以显示所有受支持的配置格式（PHP、YAML 和 XML）的配置。例如

1
2
3
4
5
6
7
8
9
10
11
12
13
.. configuration-block::

    .. code-block:: yaml

        # Configuration in YAML

    .. code-block:: xml

        <!-- Configuration in XML -->

    .. code-block:: php

        // Configuration in PHP

之前的 reStructuredText 代码片段渲染如下

1
# Configuration in YAML

所有代码示例都假定您在 Symfony 应用程序中使用该功能。如果您还需要展示如何在任何 PHP 应用程序中使用独立组件，请使用特殊格式 php-symfony 和 php-standalone，它们将像这样渲染

1
// PHP code using features provided by the Symfony framework

当前受支持的格式列表如下

标记格式 用于显示
caddy Caddy Web 服务器配置
env Bash 文件（如 .env 文件）
html+php 与 HTML 混合的 PHP 代码
html+twig 与 HTML 混合的 Twig 标记
html HTML
ini INI
php-annotations PHP 注解
php-attributes PHP 属性
php-standalone 在任何使用独立 Symfony 组件的 PHP 应用程序中使用的 PHP 代码
php-symfony 使用 Symfony 框架时的 PHP 代码示例
php PHP
rst reStructuredText 标记
terminal 将内容渲染为控制台终端（用于显示要运行的命令）
twig 纯 Twig 标记
varnish3 Varnish Cache 3 配置
varnish4 Varnish Cache 4 配置
vcl Varnish 配置语言
xml XML
yaml YAML

显示标签页

可以在文档中显示标签页。当渲染时，它们看起来类似于配置块，但标签页可以容纳任何类型的内容

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
.. tabs:: UX Installation

    .. tab:: Webpack Encore

        Introduction to Webpack

        .. code-block:: yaml

            webpack:
                # ...

    .. tab:: AssetMapper

        Introduction to AssetMapper

        Something else about AssetMapper

最常见的链接类型是 内部链接 到其他文档页面，它使用以下语法

1
:doc:`/absolute/path/to/page`

页面名称不应包含文件扩展名（.rst）。例如

1
2
3
4
5
:doc:`/controller`

:doc:`/components/event_dispatcher`

:doc:`/configuration/environments`

链接页面的标题将自动用作链接的文本。如果您想修改该标题，请使用此替代语法

1
:doc:`Doctrine Associations </doctrine/associations>`

注意

虽然它们在技术上是正确的，但请避免使用如下的相对内部链接，因为它们会破坏生成的 PDF 文档中的引用

1
2
3
4
5
:doc:`controller`

:doc:`event_dispatcher`

:doc:`environments`

链接到特定页面章节 遵循不同的语法。首先，在您要链接到的章节上方定义一个目标（语法：.. _ + 目标名称 + :）

1
2
3
4
5
6
7
8
9
# /service_container/autowiring.rst

# define the target
.. _autowiring-calls:

Autowiring other Methods (e.g. Setters and Public Typed Properties)
-------------------------------------------------------------------

// section content ...

然后，使用 :ref:: 指令从另一个文件链接到该章节

1
2
3
# /reference/attributes.rst

:ref:`Required <autowiring-calls>`

链接到 API 遵循不同的语法，您必须指定链接资源的类型（class 或 method）

1
2
3
:class:`Symfony\\Component\\Routing\\Matcher\\ApacheUrlMatcher`

:method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`

链接到 PHP 文档 遵循非常相似的语法

1
2
3
4
5
:phpclass:`SimpleXMLElement`

:phpmethod:`DateTime::createFromFormat`

:phpfunction:`iterator_to_array`

新功能、行为变更或弃用

如果您正在编写 Symfony 中新增的功能、更改或弃用，您应该在更改描述之前加上相应的指令和简短描述

对于新功能或行为变更，请使用 .. versionadded:: 7.x 指令

1
2
3
.. versionadded:: 7.2

    ... ... ... was introduced in Symfony 7.2.

如果您正在编写行为变更文档，简要描述行为是如何变化的可能会有所帮助

1
2
3
4
.. versionadded:: 7.2

   ... ... ... was introduced in Symfony 7.2. Prior to this,
   ... ... ... ... ... ... ... ... .

对于弃用，请使用 .. deprecated:: 7.x 指令

1
2
3
.. deprecated:: 7.2

    ... ... ... was deprecated in Symfony 7.2.

每当发布 Symfony 的新主要版本（例如 8.0、9.0 等）时，都会从上一个主要版本的 x.4 分支创建一个新的文档分支。此时，所有主要版本较低的 Symfony 版本的 versionadded 和 deprecated 标签都将被删除。例如，如果今天发布了 Symfony 8.0，则会从新的 8.0 分支中删除 7.0 到 7.4 的 versionadded 和 deprecated 标签。

这项工作，包括代码示例，均根据 Creative Commons BY-SA 3.0 许可协议获得许可。
目录
    版本