Стандарты документации
Дата оновлення перекладу 2024-07-17
Стандарты документации
Вклады должны следовать этим стандартам, чтобы соответствовать стилю и тону остальной документации Symfony.
Sphinx
- Для разных уровней заголовков были выбраны следующие символы: уровень 1
-
=
(знак равно), уровень 2 --
(дефис), уровень 3 -~
(тильда), уровень 4 -.
(точка) и уровень - 5"
(двойные кавычки); - Каждая строка должна прерываться примерно после первого слова, которое заходит за 72 знака (так что большинство строк будут 72-78 знаков);
- Сокращение
::
предпочитается по сравнению с.. code-block:: php
, для начала блока PHP-кода (см. документацию Sphinx, чтобы узнать, когда нужно использовать сокращение); - Встраиваемые гиперссылки не используются. Разделяйте ссылки и их целевое описание, которое вы добавляете внизу страницы;
- Встраиваемая разметка должна закрываться на той же строчке, что и открывающая строка кода;
Пример
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
Пример
======
Когда вы работаете над документами, вам нужно следовать
стандартам `Документации Symfony`_.
Уровень 2
---------
PHP-пример будет::
echo 'Привет, мир';
Уровень 3
~~~~~~~~~
.. code-block:: php
echo 'Вы не можете использовать сокращение :: здесь';
.. _`Документации Symfony`: https://symfony.com/doc
Примеры кода
- Код следует Стандартам кодирования Symfony, а также Стандартам кодирования Twig;
- Примеры кода должны выглядеть настоящими для контекста веб-приложения. Избегайте
абстрактных или тривиальных примеров (
foo
,bar
,demo
, и т.д.); - Код должен следовать Лучшим практикам Symfony.
- Используйте
Acme
, когда код требует имя поставщика; - Используйте
example.com
в качестве домена шаблонов URL, аexample.org
иexample.net
, когда требуются дополнительные домены. Все эти домены зарезервированы IANA. - Чтобы избежать горизонтальной прокрутки блоков кода, мы предпочитаем разрывать строчку правильно, если она превышает 85 знаков;
- Когда вы сворачиваете одну или больше строчек кода, поместите
...
в комментарии в точке сворачивания. Эти комментарии:// ...
(php),# ...
(yaml/bash),{# ... #}
(twig),<!-- ... -->
(xml/html),; ...
(ini),...
(text); - Когда вы сворачиваете часть строчки, например, значение переменной, поместите
...
(без комментария) в точке сворачивания; Описание свёрнутого кода: (необязательно)
- Если вы сворачиваете несколько строк: описание сворачивания может быть помещено
после
...
; - Если вы сворачиваете только часть строки: описание может быть размещено перед строкой;
- Если вы сворачиваете несколько строк: описание сворачивания может быть помещено
после
- Если это полезно пользователю, пример PHP-кода должен начинаться с объявления пространства имён;
- При ссылании на классы, убедитесь, что вы показали утверждения
use
сверху вашего блока кода. Вам не нужно показывать все утвержденияuse
в каждом примере, просто покажите те, которые использются в блоке кода; - Если это полезно,
codeblock
должен начинаться с комментария, содержащего имя файла в блоке кода. Не помещайте пустую строчку после этого комментария, кроме слуаев, когда следующая строчка - тоже комментарий; - Вы должны помещать
$
перед каждой строчкой разрыва.
Форматы
Примеры конфигурации должны отображать все поддерживаемые форматы, использующие блоки конфигурации . Поддерживаемые форматы (в их порядке):
- Конфигурация (включая сервисы): YAML, XML, PHP
- Маршрутизация: Атрибуты, YAML, XML, PHP
- Валидация: Атрибуты, YAML, XML, PHP
- Отображение Doctrine: Атрибуты, YAML, XML, PHP
- Перевод: XML, YAML, PHP
- Примеры кода (если применимо): PHP Symfony, PHP Standalone
Пример
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
// src/Foo/Bar.php
namespace Foo;
use Acme\Demo\Cat;
// ...
class Bar
{
// ...
public function foo($bar): mixed
{
// установите foo со значением bar
$foo = ...;
$cat = new Cat($foo);
// ... проверьте, имеет ли $bar правильное значение
return $cat->baz($bar, ...);
}
}
Caution
В YAML вам нужно размещать пробел после {
и перед }
(например,
{ _controller: ... }
), но это не нужно делать в Twig (например,
{'hello' : 'value'}
).
Файлы и каталоги
- При ссылании на каталоги, всегда добавляйте закрывающий слэш, чтобы избежать
путаницы с обычными файлами (например, "выполните скрипт
console
, расположенный в каталогеbin/
"). - При ссылании только на расширения файла, вам нужно включать начальную точку для
каждого расширения (например, "XML файлы используют расширение
.xml
"). Когда вы перечисляете иерархию файлов / каталогов Symfony, используйте
your-project/
в качестве каталога верхнего уровня. Например:1 2 3 4 5
your-project/ ├─ app/ ├─ src/ ├─ vendor/ └─ ...
Изображения и диаграммы
- Диаграммы должны соответствовать стилю документации Symfony. Они создаются с помощью приложения Dia, чтобы все могли их редактировать. См. README на GitHub для получения инструкций по их созданию.
Все изображения и диаграммы должны содержать alt-описания:
- Делайте описания краткими, не дублируйте информацию, окружающую рисунок;
- Описывайте сложные диаграммы в тексте, окружающем диаграмму, а не в alt-описании.
В этих случаях alt-описание должно содержать описание того, где можно найти более длинное описание (например, "Эти элементы описаны далее в следующих разделах"); - Начинайте описания с заглавной буквы и заканчивайте точкой;
- Не начинайте описания со слов "Скриншот", "Диаграмма" и т. д., за исключением
случаев, когда полезно знать точный тип (например, конкретный тип диаграммы).
1 2 3 4 5 6 7 8
.. image:: /_images/example-screenshot.png
:alt: Some concise description of the screenshot.
.. raw:: html
<object data="_images/example-diagram.svg" type="image/svg+xml"
alt="Some concise description."
></object>
Стандарты английского языка
Документация Symfony использует английский диалект США, часто называемый американским английским. Оксфордский словарь американского английского используется в качестве словарного источника.
Кроме того, документация следует таким правилам:
Названия разделов: используйте вариант капитализации начальных букв всех слов в предложении, кроме слов замкнутого класса (см. статью Википедии о заголовках и названиях).
Например: В Моём Свежем Калифорнийском Изюме Есть Витамины
- Пунктуация: избегайте использования серийных запятых;
- Местоимения: избегайте использования нозизма и всегда используйте вы вместо мы. (Т.е. избегайте точки зрения первого лица: используйте второе);
Генденрно-нейтральный язык: при ссылании на гипотетического человека, например, "пользователя с cookie сессии", исползуйте гендерно-нейтральные местоимения (они, их, им). Например, вместо:
- он или она, используйте они
- ему или ей, используйте им
- его или её, используйте их
Избегайте уничижительных слов: Вещи, которые кажутся "очевидными" или "простыми" ддя человека, пишущего документацию, могут быть абсолютно противоположными для читателя. Чтобы гарантировать, что всем комфортно при прочтении документации, постарайтесь избегать слов вроде:
- по сути
- очевидно
- легко/с лёгкостью
- просто
- логично
- всего лишь
- конечно
- быстро
- тривиально
- Сокращения допускаются: к примеру, вы можете написать как
you would
, так иyou'd
, какit is
, так иit's
, и т.д.