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), ... (текст);
• Коли ви згортаєте частину рядку, наприклад, значення змінної, розмістіть ... (без коментаря) у точці згортання;

• Опис згорнутого коду (необовʼязково):

  • Якщо ви згортаєте декілька рядків: опис згортання може бути розмішено після ...;
  • Якщо ви згортаєте лише частину рядку: опис може бути розміщено перед рядком;
• Якщо це корисно для користувача, приклад PHP-коду повинен починатися з оголошення простору імен;
• При посиланні на класи, переконайтеяс, що ви показали ствердження use зверху вашого блоку коду. Вам не потрібно показувати всі ствердження use в кожному прикладі, просто покажіть ті, які використовуються у блоці коду;
• Якщо це корисно, codeblock повинен починатися з коментаря, який містить імʼя файлу у блоці коду. Не розміщуйте порожній рядок після цього коментаря, окрім випадків, коли наступний рядок коду - також коментар;
• Ви повинні розміщувати $ перед кожним рядком розриву.

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, ...);
    }
}

Файли та каталоги

• При посиланні на каталоги, завжди додавайте замикаючий слеш, щоб уникнути плутанини зі звичайними файлами (наприклад, "виконайте скрипт console, розташований у каталозі bin/").
• При посиланні лише на розширення файлу, вам потрібно включати початкову точку для кожного розширення (наприклад, "XML-файли використовують розширення .xml").

• Коли ви перераховуєте ієрархію файлів/каталогів Symfony, використовуйте your-project/ в якості каталогу верхнього рівня. Наприклад:

  1
  2
  3
  4
  5

  your-project/
  ├─ app/
  ├─ src/
  ├─ vendor/
  └─ ...

Зображення та діаграми

• Діаграми повинні відповідати стилю документів Symfony. Вони створюються за допомогою додатку Dia, щоб будь-хто міг їх редагувати. Зверніться до README на GitHub для отримання інструкцій щодо їх створення.

• Всі зображення та діаграми повинні містити 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 використовує англійський діалект США, який частон називають американською англійською. Оксфордський словник американської англійської використовується в якості словникового джерела.

Крім того, документація дотримується таких правил:

• Назви розділів: використовуйте варіант капіталізації початкових літер усіх слів у реченні, окрім слів замкненого класу (див. статтю Вікіпедії про заголовки та назви).

  Наприклад: В Моємі Свіжому Каліфорнійському Ізюмі Є Вітаміни

• Пунктуація: уникайте використання серійних ком;
• Займенники: уникайте використання нозізму і завжди використовуйте ви замість ми. (Тобто, уникайте точки зору першої особи: використовуйте другу);

• Генденрно-нейтральна мова: при посилання на гіпотетичну людину, наприклад, "користувача з кукі сесії", використовуйте гендерно-нейтральні займенники (вони, їх, їм). Наприклад, замість:

  • він або вона, використовуйте вони
  • йому або їй, використовуйте їм
  • його або її, використовуйте їх

• Уникайте принизливих слів: Речі, які здаються "очевидними" або "простими" для особи, яка їх документує, можуть бути абсолютно протилежними для читача. Щоб переконатися, що всім комфортно читати документацію, намагайтеся уникати слів типу:

  • в принципі
  • очевидно
  • лего/з легкістю
  • просто
  • логічно
  • звичайно
  • швидко
  • просто
  • тривіально
• Скорочення дозволені: наприклад, ви можете написати як you would, так і you'd, як it is, так і it's тощо.