Формат документации¶
Документация 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
1
# Конфигурация на YAML
- XML
1
<!-- Конфигурация на XML -->
- PHP
1
// Конфигурация на PHP
Текущий список поддерживаемых форматов следующий:
Формат разметки | Используйте это для отображения |
---|---|
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
.
Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.