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 должен начинаться с комментария, содержащего имя файла в блоке кода. Не помещайте пустую строчку после этого комментария, кроме слуаев, когда следующая строчка - тоже комментарий;
• Вы должны помещать $ перед каждой строчкой разрыва.

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-описании.
    В этих случаях 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, и т.д.