Стандари документації
Дата оновлення перекладу 2024-05-13
Стандари документації
Внески повинні дотримуватися цих стандартів, щоб відповідати стилю та тону решти документації 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 Best.
- Використовуйте
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-описах має бути вказано, де можна знайти довший опис (наприклад, "Ці елементи описані далі в наступних розділах");
- Починайте описи з великої літери і закінчуйте крапкою;
- Не починайте зі слів "Знімок екрана", "Діаграма" і т.д., за винятком випадків, коли корисно знати точний тип (наприклад, конкретний тип діаграми).
Стандарти англійської мови
Документація Symfony використовує англійський діалект США, який частон називають американською англійською. Оксфордський словник американської англійської використовується в якості словникового джерела.
Крім того, документація дотримується таких правил:
Назви розділів: використовуйте варіант капіталізації початкових літер усіх слів у реченні, окрім слів замкненого класу (див. статтю Вікіпедії про заголовки та назви).
Наприклад: В Моємі Свіжому Каліфорнійському Ізюмі Є Вітаміни
- Пунктуація: уникайте використання серійних ком;
- Займенники: уникайте використання нозізму і завжди використовуйте ви замість ми. (Тобто, уникайте точки зору першої особи: використовуйте другу);
Генденрно-нейтральна мова: при посилання на гіпотетичну людину, наприклад, "користувача з кукі сесії", використовуйте гендерно-нейтральні займенники (вони, їх, їм). Наприклад, замість:
- він або вона, використовуйте вони
- йому або їй, використовуйте їм
- його або її, використовуйте їх
Уникайте принизливих слів: Речі, які здаються "очевидними" або "простими" для особи, яка їх документує, можуть бути абсолютно протилежними для читача. Щоб переконатися, що всім комфортно читати документацію, намагайтеся уникати слів типу:
- в принципі
- очевидно
- лего/з легкістю
- просто
- логічно
- звичайно
- швидко
- просто
- тривіально
- Скорочення дозволені: наприклад, ви можете написати як
you would
, так іyou'd
, якit is
, так іit's
тощо.