Формат документации

Дата обновления перевода 2024-07-17

Формат документации

Документация Symfony использует reStructuredText в качестве языка разметки, и Sphinx для генерирования документации в форматах, читаемых конечными пользователями, вроде HTML и PDF.

reStructuredText

reStructuredText это синтаксис разметки простого текста, схожий с Markdown, но намного более строгий в синтаксисе. Если вы новичок в reStructuredText, потратьте немного времени на то, чтобы ознакомиться с этим форматом, прочитав существующий исходный код документации Symfony.

Если вы хотите узнать больше об этом формате, посмотрите туториал reStructuredText Primer и Справочник reStructuredText.

Caution

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

  • Списки начинаются с начала строки (отступы запрещены);
  • Блоки линейного кодирования используют двойные кавычки (``like this``).

Sphinx

Sphinx - это система построения, которая предоставляет инструменты для создания документации из документов reStructuredText. Таким образом, она добавляет новые директивы и интерпретированные текстовые роли в стандартную разметку reST. Прочтит больше о Конструкциях разметки Sphinx.

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

PHP является маркером синтаксиса, применяемым ко всем блокам кода. Вы можете изменить это с помощью директивы code-block:

1
2
3
.. code-block:: yaml

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

Note

Кроме всех основных языков программирования, маркер синтаксиса поддерживает все виды языков разметки и конфигурации. Промотрите список поддерживаемых языков на вебсайте маркера синтаксиса.

Блоки конфигурации

Каждый раз, когда вы добавляете пример конфигурации, используйте директиву 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

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

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

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

?????? ???????? ??????????? ??? ??? ???????????
caddy ???????????? ???-??????? Caddy
env Bash-????? (????????, ????? .env)
html+php PHP-???, ????????? ? HTML
html+twig ???????? Twig, ????????? ? HTML
html HTML
ini INI
php-annotations PHP-?????????
php-attributes ???????? PHP
php-standalone PHP-???, ??????? ????? ???????????? ? ????? ?????????? PHP, ???????????? ????????? ?????????? Symfony
php-symfony ?????? PHP-???? ??? ????????????? ?????????? Symfony
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 </doctrine/associations>`

Note

Несмотря на то, что технически это правильно, избегайте использования релятивных внутренних ссылок, как следующие, потому как они нарушают ссылки в сгенерированной 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

# определить цель
.. _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.