Введение в rst-форматирование
Описание основных принципов оформления реструктурированного текста - reStructured Text, или rst. Текст в данном формате активно используется для подготовки документации python-разработчиками, может обрабатыватся CMS Plone для вывода в форматированном виде статей и т.п.
Наиболее употребимые элементы оформления rSt
============================================
1. Параграф
-----------
**Параграф** - основной блок документа. Представляет собой куски текста, разделенные одной или более пустыми строчками. Следует обратить внимание,
что выравнивание содержимого параграфа играет значение: все строки параграфа должны находиться на равном расстоянии от левого края строки.
2. Цветовое выделение фрагментов текста
---------------------------------------
Для того чтобы сделать часть текста изображенной наклонной (*italic*) следует использовать символ * справа и слева от выделяемого текста::
*этот текст будет иметь вид italic*
**Результат**:
*этот текст будет иметь вид italic*.
Для того чтобы сделать часть текста изображенной жирным шрифтом (**boldface**) следует использовать удвоенный символ ** справа и слева от выделяемого текста::
**этот текст будет иметь вид boldface**
**Результат**:
**этот текст будет иметь вид boldface**.
Для выделения цитируемых кусков программного кода (и чего ещё ?) следует использовать удвоенный символ обратных кавычек ` справа и слева от выделяемого текста::
``этот текст будет выделен как програмный код``
**Результат**:
``i = 1``
Если приведенные выше символы (\*, \*\*, \`) встречаются в выделяемом ими фрагменте, то в этом фрагменте перед этими символами следует ставить символ '\\' ('обратный слэш').
Следует помнить: выделения не могут быть вложенными, выделяемый фрагмент текста НЕ должен начинаться с пробела (* неправильно выделенный фрагмент*).
3. Списки
---------
Для организации списка из нескольких элементов следует поместить символ * в начале параграфа (то есть первому элементу списка) и расположить остальные
элементы на следующих ниже строчках, соблюдая чтобы их выравнивание слева совпадало с выравниваение первого элемента::
* Первый элемент списка.
* Второй элемента списка,
располагающийся на двух строках.
**Результат**:
* Первый элемент списка.
* Второй элемента списка,
располагающийся на двух строках.
Список можно сделать автонумерованным если использовать символ #::
#. Первый элемент нумерованного списка.
#. Второй элемент нумерованного списка.
**Результат**:
#. Первый элемент нумерованного списка.
#. Второй элемент нумерованного списка.
Для того, чтобы сделать нумерованный список следует заменить символ * на номер::
5. Первый элемент нумерованного списка.
6. Второй элемент нумерованного списка.
**Результат**:
5. Первый элемент нумерованного списка.
6. Второй элемент нумерованного списка.
Список может иметь произвольный уровень вложенности, то есть иметь дочерние списки. Например::
* Первый элемент списка.
* Второй элемент с дочерним списком.
* Первый элемент дочернего списка.
* Второй элемент дочернего списка.
* Третий элемент списка.
**Результат**:
* Первый элемент списка.
* Второй элемент с дочерним списком.
* Первый элемент дочернего списка.
* Второй элемент дочернего списка.
* Третий элемент списка.
4. Оформление терминов с определениями
--------------------------------------
Для оформления терминов, имеющих определение следует использовать следующий формат::
Термин1
Выравненное по левому краю определение этого термина.
Выравненный по левому краю второй параграф определения (может отсутствовать).
Термин2
Определение следующего термина.
**Результат**:
Definition lists:
Термин1
Выровненное по левому краю определение этого термина.
Выровненный по левому краю второй параграф определения (может отсутствовать).
Термин2
Определение следующего термина.
5. Гиперссылки и e-mail
-----------------------
Для отрисовки ссылки на внешний http-ресурс следует использовать синтаксис::
Гугль
**Результат**:
Гугль
6. Заголовки
------------
Заголовки разделов и подразделов выделяются специальными подчёркиванием, состоящим, например, из символа = или -::
Заголовок
=========
**Результат**:
Заголовок
=========
Между заголовком и левым краем не должно быть пробелов. Вложенные заголовки (заголовки подтем) должны иметь разные стили подчеркивания::
Главный заголовок
=================
Подзаголовок 1
--------------
Подзаголовок 2
++++++++++++++
**Результат**:
Главный заголовок
=================
Подзаголовок 1
--------------
Подзаголовок 2
++++++++++++++
Заголовок может выделен одновременно подчеркиванием и надчеркиванием (из одного и того же символа)::
=========
Заголовок
=========
Число символов в под- и надчеркивании должно соответствовать длине названия выделяемого заголовка.
7. Рисунки
----------
Вставка файла рисунка gnu.png осуществляется с помощью директивы::
.. image:: gnu.png
Имя файла gnu.png должно быть указано либо относительно текущего rst-файла, либо относительно каталога самого верхнего уровня.
8. Сноски
---------
Для добавления сноски следует использовать синтаксис [\#name]_ (где name - произвольное латинское имя)::
Здесь ссылаемся куда-то [#link1]_
После этого необходимо добавить внизу документа рубрику с названием 'Сноски', под которой указать куда ведет ссылка::
.. rubric::Сноски
.. [#link1] Текст сноски link1.
**Результат**:
Здесь ссылаемся куда-то [#link1]_
.. rubric::Сноски
.. [#link1] Текст сноски link1.