Стандари документації

Дата оновлення перекладу 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 тощо.