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

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

Документация 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 отображается так:

  • YAML
  • XML
  • PHP 
1
# Конфигурация на YAML

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

?????? ???????? ??????????? ??? ??? ???????????
html HTML
xml XML
php PHP
yaml YAML
twig ?????? ???????? Twig
html+twig ???????? Twig, ????????? ? HTML
html+php PHP-???, ????????? ? HTML
ini INI
php-annotations PHP-?????????

Добавление ссылок

Наиболее распространённым типом ссылок являются внутренние ссылки на другие страницы документации, которые используют следующий синтаксис:

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

Имя страницы не должно содержать расширение файла (.rst). Например:

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

:doc:`/components/event_dispatcher`

:doc:`/configuration/environments`

Название связанной страницы будет автоматически использовано в качестве текста ссылки. Если вы хотите изменить это название, используйте следующий альтернативный синтаксис:

1
:doc:`Буферизация электронной почты </email/spool>`

Note

Несмотря на то, что технически это правильно, избегайте использования релятивных внутренних ссылок, как следующие, потому как они нарушают ссылки в сгенерированной PDF-документации:

1
2
3
4
5
:doc:`controller`

:doc:`event_dispatcher`

:doc:`environments`

Ссылки на API следуют другому синтаксису, где вы должны указать тип связанного источника (namespace, class или method):

1
2
3
4
5
:namespace:`Symfony\\Component\\BrowserKit`

: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:: 2.X и краткое описание:

1
2
3
4
.. versionadded:: 2.7
    Метод ``askHiddenResponse()`` был представлен в Symfony 2.7.

Вы также можете задать вопрос и скрыть ответ. Это, в частности [...]

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

1
2
3
.. versionadded:: 2.7
    Функция ``include()`` - это новая функция Twig, которая доступна в
    Symfony 2.7. Pанее использовался тег``{% include %}``.

Каждый раз, когда выпускается новая младшая версия Symfony (например, 2.4, 2.5, и т.д.), создаётся новая ветка документации из ветки master. На данном этапе, все теги versionadded для версий Symfony, которые достигли конца периода содержания, будут удалены. Например, если бы Symfony 2.5 была выпущена сегодня, а 2.2 недавно достигла конца периода содержания, то теги 2.2 versionadded были бы удалены из новой ветки 2.5.