Формат документации
Дата обновления перевода 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
.