Виділення синтаксису

За замовчуванням для виділення синтаксису в усіх блоках коду використовується 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

Попередній відрізок reStructuredText відображається наступним чином:

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

1
2
3
4
5

:doc:`controller`

:doc:`event_dispatcher`

:doc:`environments`

Посилання на певні розділи сторінки мають інший синтаксис. По-перше, визначте ціль над розділом, на який ви будете посилатися (syntax: .. _ + target name + :):

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 використовують інший синтаксис, де вам потрібно вказати тип джерела, на яке посилаються (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:: 67x:

1
2
3

.. deprecated:: 7.2

    ... ... ... застаріла в Symfony 7.2.

Щоразу, коли випускається нова старша версія Symfony (наприклад, 6.0, 7.0 і т.д.), створюється нова гілка документації створюється з гілки x.4 попередньої старшої версії. На цьому етапі всі теги versionadded та deprecated для версій Symfony, які мають нижчу старшу версію, буде видалено. Наприклад, якщо Symfony 6.0 була випущена сьогодні, то для версій від 5.0 до 5.4 versionadded і deprecated буде видалено з нової гілки 6.0.