Структура

Для начала стоит отметить, что название "Structured Text" ("Структурированный Текст") не слишком удачно. На самом деле, это больше напоминает "Relaxed Text"("Нестрогий Текст"), в котором используются устойчивые обороты. Эти обороты интерпртируются HTML-конвертером и получается "Очень Структурированный Текст", который может использоваться веб-браузером.

Базовый распознаваемый паттерн --- параграф (quickref). Это кусок текста, отделённый пустыми строками(одной достаточно). У параграфов должны быть одинаковые отступы, то есть, количество пробелов в левом верхнем углу. Параграфы, начинающиеся с отступа, превращаются в параграфы-цитаты, с отступом. Например:

Это параграф. Весьма короткий.

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

А это ещё один.

Превратится в:

Это параграф. Весьма короткий.

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

А это ещё один.

Текстовые стили

(quickref)

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

Если нужно моноширное начертание, используются "``двойные обратные кавычки``". Обратите внимание, что внутри двойных обратных кавычек дальнейших махинаций уже не производится --- звёздочки "*" и т. д. оставляются в покое.

Если какой-то из "специальных символов" надо использовать в тексте, обычно все получится хорошо -- reStructuredText достаточно интеллектуален. Например, эта * звёздочка прекрасно обрабатывается. Если нужно, чтобы текст, *обособленный звёздочками* не выделялся курсивом, необходимо обозначить, что звёздочка не используется как специальный символ. Это можно сделать, поставив непосредственно перед ней обратный слэш, вот так "\*" (quickref), или окружив её двойными обратными кавычками(inline literals), вот так:

``\*``

Списки

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

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

нумерованные списки (числа, буквы или римские цифры; quickref)

Начинайте пункт с цифры или буквы с последующей точкой ".", правой скобкой ")" или окруженной скобками "( )", смотря что удобней. Все нижеследующие формы распознаются:

1. числа

A. большие буквы
   и оно продолжается на нескольких строчках

   даже два параграфа и всё такое!

a. маленькие буквы

        3.      с вложенным спсиком, начинающимся с другого числа
        4.  всё же, убедитесь, что числа идут в правильной последовательности!

I. большие римские цифры

i. маленький римские цифры

(1) снова числа

1) и снова

ненумерованные списки (quickref)

Точно так же, как и нумерованные списки, новый пункт начинается с новой строки и символа-буллита -- "-", "+" или "*":

* буллит с использованием "*"

        - вложенный список с использованием "-"

                + ещё один вложенный список

        - ещё один пункт

Превратится в:

• буллит с использованием "*"

  • вложенный список с использованием "-"

    • ещё один вложенный список

  • ещё один пункт

definition lists (quickref)

В отличие от остальных двух случаев, списки-определения стостоят из термина и определения этого термина. Формат списков-определений следующий:

what
      Списки-определения ассоциируют термин с определением.

*how*
       Термин -- это однострочная фраза.Определение -- это один или несколько
       параграфов или текстовых элементов, с отступами относительно термина.
       Пустые строки между термином и определением не разрешены.

Превратится в:

what

Списки-определения ассоциируют термин с определением.

how

Термин -- это однострочная фраза.Определение -- это один или несколько параграфов или текстовых элементов, с отступами относительно термина. Пустые строки между термином и определением не разрешены.

Преформатирование (примеры)

(quickref)

Чтобы просто вставить кусок преформатированного текста, который-никто-не-будет-трогать, завершите предыдущий параграф "::". Перформатированный блок завершится, когда текст вернётся на уровень отступа, который был у параграфа предшествующего преформатированному блоку.

Пример:

  Пробел, новые строки, пустые строки, и все виды разметок
    ( *такая* или \такая) в подобных блоках сохраняются.
Внимание, я изменил отступ
(но недостаточно)

пример завершён

В результате получится:

Пример:

  Пробел, новые строки, пустые строки, и все виды разметок
    ( *такая* или \такая) в подобных блоках сохраняются.
Внимание, я изменил отступ
(но недостаточно)

пример завершён

Обратите внимание, что если параграф состоит только из "::", то он не отображается.

::

    Это преформатированный текст, а
        последний параграф, состоящий из
        "::" --- удалён.

В результате:

Это преформатированный текст, а
    последний параграф, состоящий из
    "::" --- удалён.

Разделы

(quickref)

Чтобы разбить длинный текст на разделы, используйте заголовки разделов. Это строка текста(одно или несколько слов) с обрамлением: просто подчеркиванием, или отчеркиванием сверху и снизу, состоящим из минусов "-----", знаков равно "======", тильд "~~~~~~" или любых других неалфавитных символов: = - ` : ' " ~ ^ _ * + # < >, которые Вам нравятся. Подчеркивание отличается от отчеркивания сверху и снизу, состоящего из тех же символов. Подчеркивание/отчеркивание должны быт не корче самого заголовка. Будьте последовательны, така как одинаково обрамлённые разделы будут на одном уровне.

Часть 1 Заголовок
=================

Раздел 1.1 Заголовок
---------------------

Глава 1.1.1 Заголовок
~~~~~~~~~~~~~~~~~~~~~~

Раздел 1.2 Заголовок
----------------------

Часть 2 Заголовок
====================

Превратится в следующую структуру(проиллюстрируем на упрощённом псевдо-XML):

<section>

<title>

Часть 1 Заголовок

<section>

<title>

Раздел 1.1 Заголовок

<section>

<title>

Глава 1.1.1 Заголовок

<section>

<title>

Раздел 1.2 Заголовок

<section>

<title>

Часть 2 Заголовок

(В псевдо-XML для указания вложенности используются отступы и нет закрывающих тэгов. Нет возможности продемонстрировать обработанный результат, как в других примерах, потому что разделов не существует внутри двойных кавычек. Для конкретного примера, сравните структуру разделов этого исходного текста этого документа и его же в обработанном виде.)

Обратите внимание, что на заголовки разделов можно ссылаться, просто используя их название. Чтобы сослаться на заголовок Списки, мне достаточно написать "Списки_". Если заголовок содержит пробел(ы), как, например, текстовые стили, то нужно обрамить заголовок кавычками: "`текстовые стили`_".

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

Название Раздела
==================

...

Изображения

(quickref)

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

.. image:: images/biohazard.png

Результат:

images/biohazard.png --- это имя файла с изображением, которое надо включить в документ. На изображение не накладывается никаких ограничений(ни на формат, ни на размер, ни на что-либо ещё). Если изображение будет вставлять в HTML и есть желание указать дополнительную информацию, можно написать так:

Более подробную информацию см. в image directive documentation .

Что Дальше?

Это пособие для начинающих описывает наиболее широкоиспользуемые возможности reStructuredText, но их намного больше. Руководство пользователя Quick reStructuredText будет хорошим продолжением. За детальными подробностями стоит обратится к reStructuredText Markup Specification [1].