Руководство по стилю#

Введение#

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

Соблюдение данных стандартов поможет обеспечить единый и понятный стиль для всего проекта.

Общие принципы#

  1. Ясность: Старайтесь выражать свои мысли ясно и кратко. Используйте простой и понятный язык, чтобы ваша статья была доступна для широкой аудитории.

  2. Организация: Добавляйте статьи в логически связанные разделы и подразделы, чтобы облегчить навигацию и поиск информации.

  3. Согласованность: Поддерживайте уже согласованный стиль статей. Это включает выбор заголовков, списков, форматирования кода и прочих элементов.

  4. Корректность: Проверяйте факты и информацию, чтобы быть уверенным в их точности. Указывайте версии программного обеспечения, если это применимо.

Форматирование текста#

Заголовки#

  1. Заголовки: Используйте уровни заголовков (от H1 до H6) для обозначения важности разделов и подразделов. Старайтесь не пропускать уровни, чтобы обеспечить правильную иерархию

Название раздела
################

Заголовок 1 уровня
==================

Заголовок 2 уровня
------------------

Заголовок 3 уровня
~~~~~~~~~~~~~~~~~~

Заголовок 4 уровня
""""""""""""""""""

Нумерованные списки#

Нумерованные списки создаются с помощью символа решетки с точкой #.:

#. Один
#. Два
#. Три

Или:
5. Пять
6. Шесть
#. Семь

Маркированные списки#

Маркированные списки создаются с помощью символа звездочки * или дефиса -. Пробелы после маркера обязательны:

- Один
- Два
- Три

Вложенные списки#

- Первый уровень
    - Второй уровень
        - Третий уровень

Результат:

  • Первый уровень
    • Второй уровень

      • Третий уровень

Изображения#

Пример вставки изображения:

.. figure:: /_static/ru/img/gost/spec_19.202-78.png
       :align: center
       :alt: Пример таблицы из ГОСТ 19.202-78

       Пример таблицы из ГОСТ 19.202-78

Результат:

Альтернативный текст

Подпись к рисунку#

UML#

Пример:

.. uml::

    @startuml
    Alice -> Bob: Authentication Request
    Bob --> Alice: Authentication Response

    Alice -> Bob: Another authentication Request
    Alice <-- Bob: Another authentication Response
    @enduml

Результат:

@startuml Alice -> Bob: Authentication Request Bob --> Alice: Authentication Response Alice -> Bob: Another authentication Request Alice <-- Bob: Another authentication Response @enduml

Комментарии#

Можно оставлять комментарии, которые отображаются только в исходном файле ReST. Комментарии создаются с помощью двух точек в начале предложения ... Для создания многострочных комментариев необходимо соблюдать отступ:

.. Это комментарий
   Многострочный комментарий

ToDo#

.. TODO: Это текст TODO

  1. Выделение: Выделяйте важные термины, названия файлов, директорий или переменных с помощью курсива (название_переменной) или полужирного шрифта (важное_понятие).

  2. Программный код: Для отображения программного кода используйте директиву .. code-block:: и явно укажите язык программирования:

    .. code-block:: python

   def example_function(arg1, arg2):
       return arg1 + arg2

Вставка TAB#

Пример вставки TAB

.. tabs::

   .. tab:: Apples

      Apples are green, or sometimes red.

   .. tab:: Pears

      Pears are green.

   .. tab:: Oranges

      Oranges are orange.

Результат

Apples are green, or sometimes red.

Ссылки и перекрестные ссылки#

  1. Ссылки на другие страницы: При необходимости вставки ссылок на другие разделы вашей документации, используйте директиву :doc::

    :doc:`Ссылка на другую страницу документации <имя_файла_без_расширения>`

  2. Перекрестные ссылки: Если необходимо ссылаться на другие разделы в пределах текущей страницы, используйте внутренние якоря:

    :ref:`ссылка_на_якорь`