Выделение синтаксиса

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

        # Конфигурация на YAML

    .. code-block:: xml

        <!-- Конфигурация на XML -->

    .. code-block:: php

        // Конфигурация на PHP

Предыдущий отрезок reST отображается так:

1

# Конфигурация на YAML

1

<!-- Конфигурация на XML -->

1

// Конфигурация на PHP

Все примеры кода предполагают, что вы используете данную функцию внутри приложения Symfony. Если вам необходимо также показать, как использовать ее при работе с автономными компонентами в любом PHP-приложении, используйте специальные форматы php-symfony и php-standalone, которые будут отображаться следующим образом:

1

// PHP-код с использованием функций, предоставленных фреймворком Symfony

1

// PHP-код с использованием отдельных компонентов

Текущий список поддерживаемых форматов следующий:

Отображение вкладок

В документации есть возможность отображать вкладки. Они выглядят похоже на
блоки конфигурации при отображении, но вкладки могут иметь любой тип содержания:

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 </doctrine/associations>`

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

# определить цель
.. _autowiring-calls:

Автомонтирование других методов (например, сеттеров и свойств с публичным доступом)
-----------------------------------------------------------------------------------

// раздел содержания ...

Затем, используйте директиву :ref::, чтобы сослаться на этот раздел из другого файла:

1
2
3

# /reference/attributes.rst

:ref:`Required <autowiring-calls>`

Ссылки на API следуют другому синтаксису, где вы должны указать тип связанного источника (namespace, 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:: 6.x:

1
2
3

.. versionadded:: 7.2

    ... ... ... было представлено в Symfony 7.2.

Если вы документируете изменение поведения, может быть полезным кратко описать, как оно было изменено:

1
2
3
4

.. versionadded:: 7.2

   ... ... ... было представлено в Symfony 7.2. До этой версии,
   ... ... ... ... ... ... ... ... .

Для устаревания используйте директиву .. deprecated:: 7.x:

1
2
3

.. deprecated:: 7.2

    ... ... ... устарело в Symfony 7.2.

Каждый раз, когда выходит новая старшая версия Symfony (например, 8.0, 9.0 и т.д.), создается новая
ветка документации создается из ветки x.4 предыдущей старшей версии. В этот момент все теги versionadded и deprecated для версий Symfony, которые имеют более низкую старшую версию, будут удалены. Например, если бы Symfony 8.0 была выпущена сегодня, то теги versionadded и deprecated в
версиях с 7.0 по 7.4 были бы удалены из новой ветки 8.0.