Стиль документации#

Общее описание синтаксиса разметки reStructuredText, использующегося при создании документации.

Cинтаксис reStructuredText#

Документ с форматом разметки reStructuredText - это текстовый файл с расширением rst, в котором разметка описывается специальными текстовыми конструкциями.

Все конструкции должны отделяться друг от друга пустой строкой.

При описании конструкций важен сдвиг текста (т.е. позиция текста, с которой он начинается).

Если какая-то конструкция может содержать другие элементы разметки, то начальная позиция этих элементов должна быть больше чем начальная позиция основной конструкции. К примеру, конструкции «блоки» могут содержать другие конструкции.

.. hint::

  Текст сообщения

  .. warning::

    Это сообщение вложено в предыдущее.

Это пример вложенных сообщений, который будет выглядеть так:

Подсказка

Текст сообщения

Предупреждение

Это сообщение вложено в предыдущее.

Не все конструкции поддерживают вложенность других элементов. К примеру, простые блоки не могут иметь вложенных конструкций.

Конструкции, которые начинаются с одной и той же позиции вложены в один и тот же базовый элемент.

Подсказка

Какой-то текст в блоке.

Эта строка тоже будет считаться частью блока т.к. она начинается с той же позиции, с которой предыдущий текст блока несмотря на то, что между этими строками есть пустые.

Однако, если изменить позицию, то этот текст уже будет вложен в другую конструкцию.

Вставка изображений#

Для вставки изображений можно использовать несколько разных конструкций.

Простое изображение

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

.. image:: styles/i1.png
  :align: center
  :class: bordered

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

Иллюстрация

Для вставки иллюстраций используется figure (кнопка Ctrl+C P).

.. figure:: название-файла-изображения
   :class: bordered
   :align: center
   :height: 100px
   :width: 200px
   :scale: 50%

   Иллюстрации могут иметь заголовок

Этот элемент поддерживает автоматическую нумерацию рисунков. На странице можно нажать на этот элемент, в этом случае произойдет переход на файл с изображением. Чтобы вернуться к просмотру текста, нужно будет вернуться на прошлую страницу.

Картинка в тексте

Файл изображения может быть вставлен-в-текст вставлен в текст. Для этого необходимо использовать специальный синтаксис.

В любом месте документа описать ссылку на изображение в виде

.. |вставлен-в-текст| image:: вставляемый.png

Для использования файла вставляемый.png, который расположен в том же каталоге, что и текущий файл документации.

Использовать ссылку для вставки изображения в текст

...может быть |вставлен-в-текст| вставлен...

Подсказка

Ссылка на изображение может быть описана в любом месте текущего документа, в том числе до того места где она используется. Текст самой ссылки никак не отобразится в тексте.
У встраиваемого изображения невозможно указать параметры. В том числе размеры.

Параметры изображения

.. figure:: название-файла-изображения
   :class: bordered
   :align: center
   :height: 100px
   :width: 200px
   :scale: 50%

название-файла-изображения: Имя файла с изображением, которое необходимо вставить.
class: Содержит список классов, которые применяются к этому элементу (может быть пустым).
:class: bordered: Если установлено (по умолчанию), то вокруг изображения будет выведена рамка.
align: Устанавливает выравнивание и может принимать значения «left», «right», «center» для указания выравнивания влево, вправо и по центру соответственно.
width, height: Указание для масштабирования размера в указанный размер (в единицах px, pt, em, %).
scale: Общий масштаб изображения.

Подсказка

Любой параметр изображения (как и вообще все) может отсутствовать.

Ссылки#

Для того чтобы сослаться на какое-нибудь место в документе, в этом месте нужно создать место для ссылки. Для этого нужно использовать следующую конструкцию:

.. _название-ссылки:

название-ссылки — Имя ссылки, которое потом можно использовать для ссылки в указанное место. Название ссылки может содержать русские буквы, но не может содержать пробелов.

Подсказка

Текст ссылки занимает ровно одну строку, не может иметь вложенных конструкций и сама ссылка не может быть вложена в другие конструкции, поэтому:

Описание места ссылки необходимо начинать с первой позиции строки.
Между прошлой конструкцией и описанием места ссылки можно не оставлять пустую строку.

После того как ссылка создана ее можно использовать из любого места документации с помощью описания (кнопка Ctrl+C L):

:ref:`текст ссылки<название_ссылки>`

Здесь текст ссылки - это текст, который будет отображаться на странице, а название_ссылки - это имя ссылки на которую текст будет указывать. Символ < должен идти сразу же после конца отображаемого текста, без пробелов.

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

Предупреждение

Имена ссылок должны быть уникальны во всей документации, поэтому рекомендуется начинать их с префикса, уникального для каждого файла.

После того как ссылка написана вручную или вставлена с помощью Ctrl+C L, можно нажать Ctrl+Пробел и начать набирать текст префикса ссылки документа, где расположено имя ссылки.

../_images/link.png — Меню авто-дополнения.#

В появившемся меню будет отображаться список всех имен ссылок в текущей документации.

Заголовки#

Заголовки описываются в виде:

Текст заголовка
================

Для линии можно использовать любые символы пунктуации: *=+-~?/\ и т.д.

Текст заголовка
========================

Подзаголовок
------------------------

*********************
Еще подзаголовок
*********************

Второй раз на уровне прошлого
---------------------------------

Длина линии обозначающей заголовок должна быть не меньше длины текста заголовка. Можно использовать линии сверху, снизу или сверху и снизу заголовка - это будет обозначать одно и то же.

Предупреждение

Для того, чтобы в боковом оглавлении отображались все заголовки начиная с первого, необходимо в тексте описать два подряд заголовка одного уровня.

Символ используемый для линии первого заголовка в тексте считается самым «большим». Любой следующий заголовок с другим символом выделения будет меньше по уровню.

Если встретится заголовок выделенный линиями с таким же символом, как уже встречавшийся в тексте, то он будет расположен на том же уровне, что и прошлый.

Все типы заголовков можно посмотреть в этом разделе.

Рубрики#

Заголовок

Выделение локального подзаголовка без влияния на структуру заголовков. Т.е. выглядит как небольшой заголовок, но его текст не будет добавлен в общее содержание документа. Кнопка Ctrl+C R.

.. rubric:: Заголовок

Горизонтальный разделитель#

Пример:

Для создания горизонтальной линии разделителя, которая занимает всю ширину страницы необходимо в отдельной строке указать линию из символов «-» (минус) в количестве не менее 4 штук:

----

Предупреждение

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

Список элементов#

Список элементов создает список именованных зон. Выглядит как таблица из двух колонок, в первой всегда название элемента, а во второй его описание. Описание всегда имеет общее выравнивание для всего списка.

Список

Имя элемента:

Текст описания для элемента.

Имя другого элемента:

Текст описания и для него тоже.

Можно использовать несколько абзацев, вложив их в пункт и отделив пустой строкой от прошлого.

В отличии от таблицы, имеет очень простой синтаксис.

:Имя элемента: Текст описания для элемента.

:Имя другого элемента: Текст описания и для него тоже.

  Можно использовать несколько абзацев, вложив их в пункт и отделив пустой строкой от прошлого.

Таблица#

Пример таблицы

ЗАГОЛОВОК ТАБЛИЦЫ#
Заголовок колонки 1	Заголовок колонки 2
Текст колонки 1	Текст колонки 2
Текст2 колонки 1	Текст2 колонки 2
Текст3 колонки 1	Текст3 колонки 2

Число колонок должно совпадать со значениями указанными в widths, где указываются проценты области занимаемые колонками, вместо всех процентов можно указать «auto». Кнопка Ctrl+C Т создает шаблон таблицы с заголовками, в 2 колонки и одной строкой.

.. list-table:: ЗАГОЛОВОК
   :widths: 50 50
   :header-rows: 1

   * - Заголовок колонки 1
     - Заголовок колонки 2
   * - Текст колонки 1
     - Текст колонки 2

И т.д.

Выделенные блоки в тексте#

Простой блок

Чтобы выделить блок в тексте вот таким образом. Кнопка Ctrl+C Ctrl+C.

...выделить блок :code:`вот таким образом` необходимо...

Выделение блока без форматирования

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

Этот блок можно использовать в том случае, если необходимо вывести текст, содержащий какие-то символы форматирования.

Содержимое блока

Для создания используется кнопка: Ctrl+C C.

.. code::

  Содержимое блока

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

Блоки выделенного сдвинутого текста

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

Текст выделенный и сдвинутый

__Текст выделенный фоном

Вместо символа _ из примера выше необходимо использовать пробелы.

Блок информации с заголовком

Заголовок

Текст с информацией

Блок с информацией (кнопка Ctrl+C A).

.. admonition:: Заголовок

  Текст информации

Заголовок этого блока должен быть указан.

Выделенный блок с заголовком

Блок с заголовком (кнопка Ctrl+C O).

.. topic:: Заголовок

  Текст информации

Заголовок этого блока должен быть указан.

Блок предупреждения

Предупреждение

Текст предупреждения

Блок предупреждения, заголовок всегда «Предупреждение» (кнопка Ctrl+C W).

.. warning::

  Текст предупреждения

Блок подсказки

Подсказка

Текст примера или подсказки

Блок примера или подсказки, заголовок всегда «Подсказка» (кнопка Ctrl+C H).

.. hint::

  Текст подсказки

Требования к стилю документа#

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

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

.. ------------------------------------------------------

Эти конструкции можно использовать для того, чтобы отделять разные части документации, для облегчения зрительного восприятия текста.

Использование заголовков#

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

Для выделения заголовков необходимо использовать длинную строку (из 40 и более символов) сверху и снизу от заголовка, чтобы его легко было найти в оригинальном тексте зрительно.

Перед каждым заголовком необходимо создать место ссылки на него, как описано тут с именем, описывающем назначение раздела.

.. _документ-заголовок1:

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

.. _документ-заголовок2:

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

.. _документ-заголовок3:

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

.. _документ-заголовок4:

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

Где «документ» – это префикс текущего файла документации.

Предупреждение

Обратите внимание на перевод строки после ссылки, перед заголовком.

Оформление списков#

При описании списков одинаковых элементов, таких как описание элементов интерфейса (кнопов, надписей, переключателей), элементов меню и подобных одинаковых элементов можно использовать конструкцию список элементов.

Описание элементов интерфейса окна Выполнить.

Открыть:

Поле для ввода команды.

ОК:

Выполнить команду.

Отмена:

Закрывает диалог.

Обзор:

Открывает диалог для выбора программы для выполнения.

После выбора имя и путь программы будет занесен в поле Открыть.

Раздел ВАЖНО#

Предупреждение

Текст важного примечания и описания.

Используется для обозначения того, чтоб выделено в документе как ВАЖНО. Кнопка: Ctrl+C W.

.. warning::

  Текст описания

Раздел ПРИМЕР#

Используется для описания примеров. Если пример не влезает в блок, то используется как обозначение заголовка примера следующего далее. Кнопка: Ctrl+C O.

.. topic:: Заголовок примера

  Текстовое описание примера.

Раздел «К СВЕДЕНИЮ», «ИНФОРМАЦИЯ»#

Заголовок информации

Текстовое описание информации.

Используется для описания информации, которую нужно выделить в тексте отдельно. Кнопка: Ctrl+C А.

.. admonition:: Заголовок информации

  Текстовое описание информации.

Сочетание клавиш, «горячие клавиши»#

Кнопка: Ctrl+C K

-- сочетание клавиш :kbd:`Ctrl+Shift+V` или кнопка :kbd:`Ctrl+K` --

Элементы интерфейса#

Название кнопок, надписей, колонок и прочих элементов интерфейса, отдельных пунктов меню и т.д. Кнопка: Ctrl+C G.

-- пункт меню :guilabel:`Настройки`, нажать кнопку :guilabel:`Выполнить` --

Пункты меню#

Последовательность пунктов меню, которые необходимо выбрать. Кнопка Ctrl+C M. Пункты меню должны быть разделены текстом «–>».

:menuselection:`Программа --> Настройки --> Группа настроек`

Украшательства#

Иконки

Список возможных иконок.

Цвета

Список доступных в теме цветов.

Стиль документации

Содержание

Стиль документации#

Cинтаксис reStructuredText#

Вставка изображений#

Ссылки#

Заголовки#

Рубрики#

Горизонтальный разделитель#

Список элементов#

Таблица#

Выделенные блоки в тексте#

Требования к стилю документа#

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

Использование заголовков#

Оформление списков#

Раздел ВАЖНО#

Раздел ПРИМЕР#

Раздел «К СВЕДЕНИЮ», «ИНФОРМАЦИЯ»#

Сочетание клавиш, «горячие клавиши»#

Элементы интерфейса#

Пункты меню#

Украшательства#