================ reStructuredText ================ Базовые концепции ~~~~~~~~~~~~~~~~~ Синтаксис reStructuredText опирается на следующие концепции: * Отступы и пробелы имеют значение для команд разметки [#]_, но не имеют значения внутри текста (10 пробелов будут отображены как один); * В командах (директивах) используется символ обратной кавычки «`», который располагается на клавише с буквой ``ё`` и символом ``~``. Использование обычных одинарных кавычек в командах не приведет к желаемым результатам. .. [#] Не важно как делается отступ — пробелами или клавишей Tab, главное, чтобы они были одинакового размера. Абзацы ~~~~~~ Абзацы в reStructuredText отделяются друг от друга пустой строкой: :: Первый абзац... Строки параграфов начинаются от левой границы и отделяются параграфы друг от друга пустой строкой. Заголовки ~~~~~~~~~ reStructuredText поддерживает несколько уровней заголовков. Заголовки первого уровня (главы) подчеркиваются символом равно ``=``. Заголовки второго уровня (подглавы) подчеркиваются символом короткого тире или минуса ``-``. Заголовки третьего уровня (подпункта) подчеркиваются символом тильды ``~``. Для параграфов допускается использовать подчеркивание символами двойных кавычек ``"`` Заголовки подчеркиваются (или отбиваются сверху и снизу) с помощью небуквенных и нецифровых 7­-битных ASCII символов. Рекомендуется использовать: «``= ­ ` : ' " ~ ^ _ * + # < >``». Отбивка должна быть не короче текста заголовка. :: Заголовок 1 уровня ================== Заголовок 2 уровня ------------------ Заголовок 3 уровня ~~~~~~~~~~~~~~~~~~ Заголовок 4 уровня """""""""""""""""" Начертание ~~~~~~~~~~ Чтобы выделить текст **жирным** начертанием или *курсивным* используется обособление звездочками: :: **жирный текст** *курсив текст* .. attention:: Не допускается наличие пробелов между выделяемым словом и звездочкой, например, команда ``** жирный текст**`` не даст нужного эффекта. Начертание текста ``«как есть»`` достигается обособлением двумя обратными кавычками: :: ``«как есть»`` Нумерованные списки ~~~~~~~~~~~~~~~~~~~ Нумерованные списки создаются с помощью символа решетки с точкой ``#.``: :: #. Один #. Два #. Три Или: 5. Пять 6. Шесть #. Семь Результат: #. Один #. Два #. Три Или: 5. Пять 6. Шесть #. Семь Маркированные списки ~~~~~~~~~~~~~~~~~~~~ Маркированные списки создаются с помощью символа звездочки ``*`` или дефиса ``-``. Пробелы после маркера обязательны: :: * Один * Два * Три Результат: * Один * Два * Три Вложенные списки ~~~~~~~~~~~~~~~~ :: * Первый уровень * Второй уровень * Третий уровень Результат: * Первый уровень * Второй уровень * Третий уровень :: #. Один * Маркер #. Два #. Номер Результат: #. Один * Маркер #. Два #. Номер Комментарии ~~~~~~~~~~~ В reStructuredText можно оставлять комментарии, которые отображаются только в исходном файле ReST. Комментарии создаются с помощью двух точек в начале предложения ``..``. Для создания многострочных комментариев необходимо соблюдать отступ: :: .. Это комментарий Многострочный комментарий .. Это комментарий Много строчный комментарий .. _listing-rst: Вставка текста из других файлов ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ReST позволяет вставлять текст из других файлов: :: .. include:: имя_файла Черта (Линия) ~~~~~~~~~~~~~ Иногда возникает необходимость визуально отделить абзац, для этого можно воспользоваться чертой, достаточно поставить подряд несколько дефисов (не меньше 4-х), также можно воспользоваться нижним подчеркиванием: :: -------- ________ .. warning:: Символы черты должны быть отбиты пустыми строками до и после. .. warning:: Черта не должна завершать документ. Черта, расположенная в самом конце документа может вызывать ошибки при сборке. Ссылки ~~~~~~ Внешние ссылки создаются так: :: 1. Внешние ссылки выглядят так: ссылка_. .. _ссылка: http://librerussia.blogspot.ru/ 2. Если несколько слов, тогда так: `ссылка в несколько слов`_. .. _`ссылка в несколько слов`: http://librerussia.blogspot.ru/ 3. `Более компактная запись ссылок `_ Результат: 1. Внешние ссылки выглядят так: ссылка_. .. _ссылка: http://librerussia.blogspot.ru/ 2. Если несколько слов, тогда так: `ссылка в несколько слов`_. .. _`ссылка в несколько слов`: http://librerussia.blogspot.ru/ 3. `Более компактная запись ссылок `_ Таблицы ~~~~~~~ Создавать таблицы можно несколькими способами: :: .. table:: Заголовок таблицы (Внимание! Отступ таблицы относительно команды ..``table::`` обязателен) +------------------------+------------+----------+----------+ | Header row, column 1 | Header 2 | Header 3 | Header 4 | | (header rows optional) | | | | +========================+============+==========+==========+ | body row 1, column 1 | column 2 | column 3 | column 4 | +------------------------+------------+----------+----------+ | body row 2 | Cells may span columns. | +------------------------+------------+---------------------+ | body row 3 | Cells may | - Table cells | +------------------------+ span rows. | - contain | | body row 4 | | - body elements. | +------------------------+------------+---------------------+ .. important:: Отступ таблицы относительно команды ``.. table::`` обязателен Результат: .. table:: Заголовок таблицы (Внимание! Отступ таблицы относительно команды ``.. table::`` обязателен) +------------------------+------------+----------+----------+ | Header row, column 1 | Header 2 | Header 3 | Header 4 | | (header rows optional) | | | | +========================+============+==========+==========+ | body row 1, column 1 | column 2 | column 3 | column 4 | +------------------------+------------+----------+----------+ | body row 2 | Cells may span columns. | +------------------------+------------+---------------------+ | body row 3 | Cells may | - Table cells | +------------------------+ span rows. | - contain | | body row 4 | | - body elements. | +------------------------+------------+---------------------+ Простая таблица: :: .. table:: Простая таблица ===== ===== ======= A B A and B ===== ===== ======= False False False True False False False True False True True True ===== ===== ======= Результат: .. table:: Простая таблица ===== ===== ======= A B A and B ===== ===== ======= False False False True False False False True False True True True ===== ===== ======= Ещё один пример: :: .. table:: Простая таблица со сложной шапкой ===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ====== Результат: .. table:: Простая таблица со сложной шапкой ===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ====== Ещё один тип таблицы — CSV-таблица: :: .. csv-table:: CSV-таблица :header: "Treat", "Quantity", "Description" :widths: 15, 10, 30 "Albatross", 2.99, "On a stick!" "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be crunchy, now would it?" "Gannet Ripple", 1.99, "On a stick!" Результат: .. _cvs-table: .. csv-table:: CSV-таблица :header: "Treat", "Quantity", "Description" :widths: 15, 10, 30 "Albatross", 2.99, "On a stick!" "Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be crunchy, now would it?" "Gannet Ripple", 1.99, "On a stick!" Конструкции разметки Sphinx ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sphinx содержит дополнительные конструкции разметки, значительно расширяющие функционал, но которые не поддерживаются стандартной разметкой reStructuredText. .. _toctree-label: Автоматическое содержание ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Стандартная разметка reStructuredText поддерживает создание в отдельных документах автоматического содержания на основе заголовков. Sphinx расширяет данную функцию и позволяет автоматически создавать общее оглавление для группы документов. Файл ``index.rst`` обычно содержит автоматическое оглавление, созданное командой ``.. toctree::``: :: .. toctree:: :maxdepth: 2 :numbered: :hidden: имя_документа1 имя_документа1 имя_документа1 Команда ``.. toctree::`` имеет несколько параметров: * ``:caption:`` — создает древовидную структуру содержания; * ``:maxdepth: 1`` — уровни заголовков (1,2,3,4,5 и т.д.), включаемых в оглавление; * ``:numbered:`` — нумерация всех пунктов оглавления; * ``:hidden:`` — позволяет скрыть оглавление. После параметров через пустую строку, с отступами, идут названия включаемых файлов, без расширения. Данные названия будут автоматически преобразованы в заголовки разделов. Параметр ``:maxdepth:`` не распространяется на LaTeX-документы. Глубина оглавления в LaTeX контролируется его внутренним счетчиком, который можно настроить в файле конфигурации Sphinx ``conf.py``, указав в преамбуле значение ``\setcounter{tocdepth}{2}``. Параметр ``:hidden:`` позволяет Sphinx'у быть в курсе структуры документа, но при этом не отображать оглавление. Удобно, если ссылки на разделы будут указаны, например, на боковой панели. Подробнее об автоматическом оглавлении в Sphinx смотрите в разделе `«The TOC tree» `_ официальной документации Sphinx. .. _source-code-label: Примеры исходного кода с подсветкой синтаксиса ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sphinx поддерживает вставку примеров исходного когда с подсветкой синтаксиса на разных языках программирования. Вставка листингов осуществляется командой ``.. code-block:: <название яыка>``: :: .. code-block:: python def some_function(): interesting = False print 'This line is highlighted.' print 'This one is not...' print '...but this one is.' Результат: .. code-block:: python def some_function(): interesting = False print 'This line is highlighted.' print 'This one is not...' print '...but this one is.' Команда ``.. code-block::`` имеет следующие параметры: * ``:linenos:`` — добавляет нумерацию строк; * ``:emphasize-lines:`` — включает подсветку отдельных строк, допускается перечисление одиночных строк через запятую или групп строк через тире. Больше элементов синтаксиса reStructuredText и Sphinx можно найти `здесь `_. Вставка изображений между абзацами: :: .. figure:: _static/favicon.png :scale: 300 % :align: center :alt: Альтернативный текст Подпись изображения Легенда изображения.