Restructured Text (ReST)

О документе

Документ описывает правила оформления документации на основе генератора документации Sphinx.

Некоторые правила заимствованы из ГОСТ 2.105-95.

Форматирование

Общие правила

Имена файлов должны иметь расширение .rst.
Файлы должны быть в кодировке UTF-8.
Должен использоваться символ LF для переноса строк.
Должен использоваться отступ в 2 пробела.
На концах строк не должно быть пробельных символов (whitespaces).
В документе не должны использоваться символы табуляции.
Ширина строки не должна превышать 100 символов. Исключение: таблицы, заголовки, строки со ссылками.
В документе должна использоваться одна пустая строка для разделения абзацев и других элеменов документа (doctree elements). Исключение: блоки форматированного текста (literal blocks).
При сборке документов .rst не должно быть предупреждений. Сборка документов должна выполняться с ключом -W:
```
sphinx-build -W ...
```

Заголовки

Для заголовков должны использоваться следующие символы разметки:
- = с линией сверху — разметка заглавия документа
- = — разметка заголовков 1-ого уровня (aka chapter)
- - — разметка заголовков 2-ого уровня (aka section)
- ~ — разметка заголовков 3-ого уровня (aka subsection)
- ' — разметка заголовков 4-ого уровня (aka subsubsection)
- ` — разметка заголовков 5-ого уровня (whatever)
Например:
```
==================
Заглавие документа
==================

Заголовок 1
===========

Заголовок 2
-----------

Заголовок 3
~~~~~~~~~~~

Заголовок 4
'''''''''''

Заголовок 5
```````````
```
Разметка заголовка должна быть указана под названием заголовка.
Разметка заголовка и тело главы должны быть разделены строго одной пустой строкой.

Перечни

Перед маркером элемента перечня не должно быть отступа относительно предшествующего текста. Например:

Перечень:

* первый элемент,
* второй элемент,
* ...

Частный случай данного правила: если тело главы состоит из нумерованных абзацев, то не должно быть отступа перед абзацами. Например:

Chapter 2
---------

#. Lorem ipsum dolor sit amet, est quis eruditi in, eos altera postea in,
   eum eu vidisse complectitur. Sit putent mollis recteque in,
   audire scripta an mel. Ut qui legendos iudicabit.

#. Ei sea dictas detracto molestiae, no pri graece utamur minimum,
   te vis diam imperdiet. Cu sint constituto liberavisse vix,
   ei eum tantas eligendi constituam.

Наличие/отсутствие пустых строк должно быть единым в пределах одного перечня, Пример перечня с пустыми строками между элементами перечня:

Here are some guidelines to keep in mind when designing an application
for the cloud:

#. Be a pessimist: Assume everything fails and design backwards.

#. Put your eggs in multiple baskets: Leverage multiple providers,
   geographic regions and availability zones to accommodate for local
   availability issues. Design for portability.

#. Think efficiency: Inefficient designs will not scale. Efficient
   designs become cheaper as they scale. Kill off unneeded components or
   capacity.

Если каждый из элементов перечня занимает не более одной строки, то не рекомендуется разделять элементы пустыми строками. Например:
```
Перечни бывают:

* простые, т.е. состоящие из одного уровня членения текста;
* составные, включающие 2 и более уровней.
```

Директивы

Директивы должны иметь отступ предшествующего текста.
Опции директив (directive options) должны иметь отступ в 3 пробела относительно начала директивы.
Содержание директив (directive content) должно иметь отступ в 3 пробела относительно начала директивы.

Например:

На рисунке :numref:`dull-clouds` представлена ненастная погода.

.. figure:: dull-clouds.png
   :name: dull-clouds

   Пасмурные облака

Роли

Использование следующих ролей может быть заменено на оформление литералами (оформляются в двойных бэктиках):
- имена файлов, директорий, расширения файлов, (например, ``confini`` или :file:`conf.ini`);
- имена переменных окружения (например, ``LD_LIBRARY_PATH`` или :envvar:`LD_LIBRARY_PATH`);
- элементы кода языка программирования (макросы, функции, типы данных, поля структур и т.д.).

Прямое форматирование выражений

Если в документе приводятся поясняющие надписи, наносимые непосредственно на изготовляемое изделие (например на планки, таблички к элементам управления, подписи в слое шелкографии на печатных платах и т.п.), их выделяют шрифтом (без кавычек), например, *ВКЛ.*, *OTKЛ.*.

Содержательная часть документа

Общие правила

Символ тире (—) должен оформляться тремя символами минуса: ---.
При вводе сокращённого обозначения необходимо использовать фразу “(далее — <сокращённое обозначение>)”. Например:
```
Документ описывает программное обеспечение (далее --- ПО) для аппаратного модуля ...
```

Математические формулы

Пояснения символов и числовых коэффициентов, входящих в формулу, если они не пояснены ранее в тексте, должны быть приведены непосредственно под формулой. Пояснения каждого символа необходимо давать в той последовательности, в которой символы приведены в формуле. Первая строка пояснения должна начинаться со слова “где” без двоеточия после него. Для переменных и выражений, которые встречаются в математических выражениях должно выполняться выделение курсивом по тексту. Например:
```
Шаг определяется как количество строк кадра:

.. math::  s = \frac{r h}{2f},

где *s* --- шаг изменения выдержки, *r* --- частота кадров,
*h* --- количество строк в кадре, *f* --- частота мерцания освещения.
```

При ссылке допускается опускать слова “формула”, “неравенство”, “выражение” в соответствующем склонении перед указанием номера. Например:

.. math::
   :label: cc_rgb

   O_{RGB} = M_{FX\_RGB},

.. math::
   :label: cc_general

   O = M_{CC} \times I+V_{CC}.

Для расчёта формулы входного формата необходимо привести :eq:`cc_rgb` к виду :eq:`cc_general`.

Рисунки

Рисунки должны оформляться директивой .. figure::.
Заголовок рисунка должен начинаться с заглавной буквы. Точка в конце не ставится. Если заголовок состоит из нескольких предложений, то предложения разделяются точкой. Заголовок не должен быть пустым.
На все рисунки документа должны быть приведены ссылки в тексте документа.

При ссылке следует писать слово “рисунок” (или соответствующее склонение) с указанием его номера. Например:

Подключить видеомодуль в соответствии с рисунком :numref:`connecting-to-board`.

.. figure:: connection.png
   :scale: 80%
   :align: center
   :name: connecting-to-board

   Пример подлючения видеомодуля к отладочному модулю

Допускается помещать рисунок вдоль длинной стороны листа документа:

.. raw:: latex

   \begin{landscape}

.. figure:: connection.png
   :scale: 80%
   :align: center
   :name: connecting-to-board

   Пример подлючения видеомодуля к отладочному модулю

.. raw:: latex

   \end{landscape}

Таблицы

Заголовок таблицы должен начинаться с заглавной буквы. Точка в конце не ставится. Если заголовок состоит из нескольких предложений, то предложения разделяются точкой. Заголовок не должен быть пустым.
На все таблицы документа должны быть приведены ссылки в тексте документа.

При ссылке необходимо писать слово “таблица” (или соответствующее склонение) с указанием её номера. Например:

В таблице :numref:`standard-controls` приведён список стандартных контролов драйвера.

.. csv-table:: Список поддерживаемых стандартных контролов
   :name: standard-controls
   :file: standard-controls.csv
   :header-rows: 1
   :delim: ;
   :class: longtable

Ячейки таблицы не должны быть пустыми. При отсутствии данных ячейка должна заполняться двумя минусами -- (При заполнении одним минусом - ReST вставляет пустой список состоящий из маркера).
В конце текста ячейки таблицы точка не ставится, если содержимое ячейки состоит из нескольких слов без знаков препинания. Если ячейка таблицы содержит одно или несколько предложений, то в конце предложений ставится точка.
Заголовки граф и строк таблицы следует писать с прописной буквы, подзаголовки граф — со строчной буквы, если они составляют одно предложение с заголовком, или с прописной буквы, если они имеют самостоятельное значение. В конце заголовков и подзаголовков таблиц точки не ставят. Заголовки и подзаголовки граф указывают в единственном числе.

Допускается помещать таблицу вдоль длинной стороны листа документа:

.. raw:: latex

   \begin{landscape}

.. csv-table:: Список поддерживаемых стандартных контролов
   :name: standard-controls
   :file: standard-controls.csv
   :header-rows: 1
   :delim: ;
   :class: longtable

.. raw:: latex

   \end{landscape}

Допускается помещать таблицу с новой страницы:

.. raw:: latex

   \newpage

.. csv-table:: Список поддерживаемых стандартных контролов
   :name: standard-controls
   :file: standard-controls.csv
   :header-rows: 1
   :delim: ;
   :class: longtable

Перечни

Допускается применять внутриабзационные перечни, в случае если элементы перечня состоят из нескольких слов, без знаков препинания внутри. Номера элементов перечней в тексте ReST должны задаваться явно. Например:
```
Перечни по своей структуре бывают:

#. Внутрибазационными: а) раз, б) два, в) три.
#. Многоабзационными: ...
```
Элементы многоабзационных нумерованных перечней должны начинаться с заглавной буквы. В конце элемента должна ставиться точка. Например:
```
#. В конце текста ячейки таблицы точка не ставится.
#. Допускается помещать таблицу вдоль длинной стороны листа документа.
```
Элементы многоабзационных ненумерованных перечней должны начинаться с маленькой буквы. В конце последнего элемента должна ставиться точка. После остальных элементов ставится:
- запятая, если абзацы-элементы из нескольких слов, без знаков препинания внутри. Допускается постановка точки с запятой;
- точка с запятой, если элементы не просты, со знаками препинания внутри.

Пример документа Sphinx

Ниже представлен пример форматирования документа в соответствии с данными правилами. В примере используется исходный код данного документа.

========================
Restructured Text (ReST)
========================

.. highlight:: rst

О документе
===========

Документ описывает правила оформления документации на основе генератора документации Sphinx_.

Некоторые правила заимствованы из ГОСТ 2.105-95.

Форматирование
==============

Общие правила
-------------

#. Имена файлов должны иметь расширение ``.rst``.

#. Файлы должны быть в кодировке UTF-8.

#. Должен использоваться символ LF для переноса строк.

#. Должен использоваться отступ в 2 пробела.

#. На концах строк не должно быть пробельных символов (whitespaces).

#. В документе не должны использоваться символы табуляции.

#. Ширина строки не должна превышать 100 символов.
   Исключение: таблицы, заголовки, строки со ссылками.

#. В документе должна использоваться одна пустая строка для разделения абзацев и других элеменов
   документа (doctree elements). Исключение: блоки форматированного текста (literal blocks).

#. При сборке документов ``.rst`` не должно быть предупреждений.
   Сборка документов должна выполняться с ключом ``-W``::

     sphinx-build -W ...

Заголовки
---------

#. Для заголовков должны использоваться следующие символы разметки:

   * ``=`` с линией сверху --- разметка заглавия документа
   * ``=`` --- разметка заголовков 1-ого уровня (aka chapter)
   * ``-`` --- разметка заголовков 2-ого уровня (aka section)
   * ``~`` --- разметка заголовков 3-ого уровня (aka subsection)
   * ``'`` --- разметка заголовков 4-ого уровня (aka subsubsection)
   * ````` --- разметка заголовков 5-ого уровня (whatever)

   Например::

     ==================
     Заглавие документа
     ==================

     Заголовок 1
     ===========

     Заголовок 2
     -----------

     Заголовок 3
     ~~~~~~~~~~~

     Заголовок 4
     '''''''''''

     Заголовок 5
     ```````````

#. Разметка заголовка должна быть указана под названием заголовка.
#. Разметка заголовка и тело главы должны быть разделены строго одной пустой строкой.

Перечни
-------

#. Перед маркером элемента перечня не должно быть отступа относительно предшествующего текста.
   Например::

     Перечень:

     * первый элемент,
     * второй элемент,
     * ...

   Частный случай данного правила: если тело главы состоит из нумерованных абзацев,
   то не должно быть отступа перед абзацами. Например::

     Chapter 2
     ---------

     #. Lorem ipsum dolor sit amet, est quis eruditi in, eos altera postea in,
        eum eu vidisse complectitur. Sit putent mollis recteque in,
        audire scripta an mel. Ut qui legendos iudicabit.

     #. Ei sea dictas detracto molestiae, no pri graece utamur minimum,
        te vis diam imperdiet. Cu sint constituto liberavisse vix,
        ei eum tantas eligendi constituam.


#. Наличие/отсутствие пустых строк должно быть единым в пределах одного перечня,
   Пример перечня с пустыми строками между элементами перечня::

     Here are some guidelines to keep in mind when designing an application
     for the cloud:

     #. Be a pessimist: Assume everything fails and design backwards.

     #. Put your eggs in multiple baskets: Leverage multiple providers,
        geographic regions and availability zones to accommodate for local
        availability issues. Design for portability.

     #. Think efficiency: Inefficient designs will not scale. Efficient
        designs become cheaper as they scale. Kill off unneeded components or
        capacity.

#. Если каждый из элементов перечня занимает не более одной строки,
   то не рекомендуется разделять элементы пустыми строками. Например::

     Перечни бывают:

     * простые, т.е. состоящие из одного уровня членения текста;
     * составные, включающие 2 и более уровней.

Директивы
---------

#. Директивы должны иметь отступ предшествующего текста.
#. Опции директив (directive options) должны иметь отступ в 3 пробела относительно начала директивы.
#. Содержание директив (directive content) должно иметь отступ в 3 пробела относительно
   начала директивы.

Например::

  На рисунке :numref:`dull-clouds` представлена ненастная погода.

  .. figure:: dull-clouds.png
     :name: dull-clouds

     Пасмурные облака

Роли
----

#. Использование следующих ролей может быть заменено на оформление литералами
   (оформляются в двойных бэктиках):

   * имена файлов, директорий, расширения файлов, (например, ````confini```` или
     ``:file:`conf.ini```);

   * имена переменных окружения (например, ````LD_LIBRARY_PATH````  или
     ``:envvar:`LD_LIBRARY_PATH```);

   * элементы кода языка программирования (макросы, функции, типы данных, поля структур и т.д.).

Прямое форматирование выражений
-------------------------------

#. Если в документе приводятся поясняющие надписи, наносимые непосредственно на изготовляемое
   изделие (например на планки, таблички к элементам управления, подписи в слое шелкографии на
   печатных платах и т.п.), их выделяют шрифтом (без кавычек), например, ``*ВКЛ.*``, ``*OTKЛ.*``.

Содержательная часть документа
==============================

Общие правила
-------------

#. Символ тире_ (---) должен оформляться тремя символами минуса: ``---``.

#. При вводе сокращённого обозначения необходимо использовать фразу
   "(далее --- <сокращённое обозначение>)". Например::

     Документ описывает программное обеспечение (далее --- ПО) для аппаратного модуля ...

Математические формулы
----------------------

#. Пояснения символов и числовых коэффициентов, входящих в формулу,
   если они не пояснены ранее в тексте, должны быть приведены непосредственно под формулой.
   Пояснения каждого символа необходимо давать в той последовательности, в которой
   символы приведены в формуле. Первая строка пояснения должна начинаться со слова "где" без
   двоеточия после него. Для переменных и выражений, которые встречаются в математических
   выражениях должно выполняться выделение курсивом по тексту.
   Например::

     Шаг определяется как количество строк кадра:

     .. math::  s = \frac{r h}{2f},

     где *s* --- шаг изменения выдержки, *r* --- частота кадров,
     *h* --- количество строк в кадре, *f* --- частота мерцания освещения.

#. При ссылке допускается опускать слова "формула", "неравенство", "выражение" в соответствующем
   склонении перед указанием номера. Например::

     .. math::
        :label: cc_rgb

        O_{RGB} = M_{FX\_RGB},

     .. math::
        :label: cc_general

        O = M_{CC} \times I+V_{CC}.

     Для расчёта формулы входного формата необходимо привести :eq:`cc_rgb` к виду :eq:`cc_general`.

Рисунки
-------

#. Рисунки должны оформляться директивой ``.. figure::``.

#. Заголовок рисунка должен начинаться с заглавной буквы. Точка в конце не ставится.
   Если заголовок состоит из нескольких предложений, то предложения разделяются точкой.
   Заголовок не должен быть пустым.

#. На все рисунки документа должны быть приведены ссылки в тексте документа.

#. При ссылке следует писать слово "рисунок" (или соответствующее склонение) с указанием его
   номера. Например::

     Подключить видеомодуль в соответствии с рисунком :numref:`connecting-to-board`.

     .. figure:: connection.png
        :scale: 80%
        :align: center
        :name: connecting-to-board

        Пример подлючения видеомодуля к отладочному модулю

#. Допускается помещать рисунок вдоль длинной стороны листа документа::

     .. raw:: latex

        \begin{landscape}

     .. figure:: connection.png
        :scale: 80%
        :align: center
        :name: connecting-to-board

        Пример подлючения видеомодуля к отладочному модулю

     .. raw:: latex

        \end{landscape}

Таблицы
-------

#. Заголовок таблицы должен начинаться с заглавной буквы. Точка в конце не ставится.
   Если заголовок состоит из нескольких предложений, то предложения разделяются точкой.
   Заголовок не должен быть пустым.

#. На все таблицы документа должны быть приведены ссылки в тексте документа.

#. При ссылке необходимо писать слово "таблица" (или соответствующее склонение) с указанием её
   номера.
   Например::

     В таблице :numref:`standard-controls` приведён список стандартных контролов драйвера.

     .. csv-table:: Список поддерживаемых стандартных контролов
        :name: standard-controls
        :file: standard-controls.csv
        :header-rows: 1
        :delim: ;
        :class: longtable

#. Ячейки таблицы не должны быть пустыми. При отсутствии данных ячейка должна заполняться
   двумя минусами ``--`` (При заполнении одним минусом ``-`` ReST вставляет пустой список
   состоящий из маркера).

#. В конце текста ячейки таблицы точка не ставится, если содержимое ячейки состоит
   из нескольких слов без знаков препинания.
   Если ячейка таблицы содержит одно или несколько предложений, то в конце предложений ставится
   точка.

#. Заголовки граф и строк таблицы следует писать с прописной буквы, подзаголовки граф ---
   со строчной буквы, если они составляют одно предложение с заголовком, или с прописной буквы,
   если они имеют самостоятельное значение. В конце заголовков и подзаголовков таблиц точки
   не ставят.
   Заголовки и подзаголовки граф указывают в единственном числе.

#. Допускается помещать таблицу вдоль длинной стороны листа документа::

     .. raw:: latex

        \begin{landscape}

     .. csv-table:: Список поддерживаемых стандартных контролов
        :name: standard-controls
        :file: standard-controls.csv
        :header-rows: 1
        :delim: ;
        :class: longtable

     .. raw:: latex

        \end{landscape}

#. Допускается помещать таблицу с новой страницы::

     .. raw:: latex

        \newpage

     .. csv-table:: Список поддерживаемых стандартных контролов
        :name: standard-controls
        :file: standard-controls.csv
        :header-rows: 1
        :delim: ;
        :class: longtable

Перечни
-------

#. Допускается применять внутриабзационные перечни, в случае если элементы перечня состоят из
   нескольких слов, без знаков препинания внутри.
   Номера элементов перечней в тексте ReST должны задаваться явно. Например::

     Перечни по своей структуре бывают:

     #. Внутрибазационными: а) раз, б) два, в) три.
     #. Многоабзационными: ...

#. Элементы многоабзационных нумерованных перечней должны начинаться с заглавной буквы.
   В конце элемента должна ставиться точка. Например::

   #. В конце текста ячейки таблицы точка не ставится.
   #. Допускается помещать таблицу вдоль длинной стороны листа документа.

#. Элементы многоабзационных ненумерованных перечней должны начинаться с маленькой буквы.
   В конце последнего элемента должна ставиться точка. После остальных элементов ставится:

   * запятая, если абзацы-элементы из нескольких слов, без знаков препинания внутри.
     Допускается постановка точки с запятой;
   * точка с запятой, если элементы не просты, со знаками препинания внутри.

Пример документа Sphinx
=======================

Ниже представлен пример форматирования документа в соответствии с данными правилами.
В примере используется исходный код данного документа.

.. literalinclude:: rest.rst
   :language: rst

.. _Sphinx: http://sphinx-doc.org
.. _тире: https://ru.wikipedia.org/wiki/Тире