Основы синтаксиса reStructuredText#

В файле index.rst мы видим следующий текст:

..  Example documentation master file, created by
    sphinx-quickstart on Tue Jun  7 08:39:22 2022.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.

Двумя точками — .. — в rst помечаются закомментированные строки. Они не идут на сайт. Их видят только те, кто пишет документацию. Вы можете помечать таким образом строки документации, которая пока не нужна, или оставлять комментарии для других технических писателей.

Этот текст можно спокойно удалить, он нам дальше не понадобится.

Дальше идёт заголовок, который мы видим на главной странице сайта. Он подчёркивается знаками равенства. Так помечается главный заголовок в документе.

Welcome to Example's documentation!
===================================

Директива toctree отвечает за дерево документации. С помощью неё вы создаёте ссылки на страницы сайта.

  1. Параметр maxdepth отвечает за отображаемую вложенность в данном оглавлении. То есть фактическая вложенность может быть любой, но в данном случае она будет отображаться не глубже второго уровня.

  2. Параметр caption позволяет нам оставить какой-то текст перед оглавлением. В данном случае это «Contents:».

..  toctree::
    :maxdepth: 2
    :caption: Contents:

Attention

Если вы создадите страницу и не укажите её ни в одном toctree, то Sphinx укажет на эту ошибку и не отобразит вашу страницу ни в одном оглавлении.

Вот так будет выглядеть главная страница для этой статьи в файле index.rst:

Index.rst

sphinx-101-8-index.rst.png

Под моим toctree появился список наименований:

deploy
first-setup
git
index (главная страница)
main-syntax-rst
project-setup
quick-start

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

File List

На сайте эти пункты станут отображаться только после того, как вы зададите заголовок пункта в самом файле. Не забудьте подчеркнуть заголовок знаками =. Пункт first-setup отвечает за пункт статьи “Первоначальные настройки”. И вот так будет выглядеть оглавление в нём:

Первоначальные настройки
========================

Note

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

Заголовки#

Для построения структуры в документе могут быть заголовки разного размера. Чтобы понять, как это выглядит, давайте откроем project-setup. Там есть подзаголовки VS Code, Index.rst, Conf.py. В коде они обозначаются следующим образом:

VS Code
-------

Index.rst
---------

Conf.py
-------

Дефисами помечаются заголовки, которые ниже по иерархии, чем заголовки подчёркнутые знаками равенства. Иерархия в целом может выглядеть так:

Уровень 1
=========

Пункт 1.

Уровень 2
---------

Пункт 2.

Уровень 3
+++++++++

Пунт 3.

Уровень 4
'''''''''

Пункт 4.

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

Note

Некоторые символы лучше подходят для заголовков, чем другие. В документация по reStructuredText рекомендуют использовать только следующие:

= - ` : . ' " ~ ^ _ * + #.

Списки#

Списки составляются с помощью цифр и знаков #. и *.

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

Его можно задать двумя способами:

Цифрами:

1.  Первый пункт.
2.  Второй пункт.
3.  Третий пункт.

  1. Первый пункт.

  2. Второй пункт.

  3. Третий пункт.

Символами:

#.  Первый пункт.
#.  Второй пункт.
#.  Третий пункт.

  1. Первый пункт.

  2. Второй пункт.

  3. Третий пункт.

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

4.  Четвёртый пункт.
#.  Пятый пункт.
#.  Шестой пункт.

  1. Четвёртый пункт.

  2. Пятый пункт.

  3. Шестой пункт.

В этом случае нумерация продолжится после цифры 4.

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

Список задаётся с помощью символа *:

*   первый пункт,
*   второй пункт,
*   третий пункт.

  • первый пункт,

  • второй пункт,

  • третий пункт.

Отступы#

При написании списков, старайтесь делать одинаковые отступы. Особенно если делаете вложенные списки. А сами списки в тексте отделяются пустыми строками:

После этого текста идёт список:

#.  Первый пункт.

    *   первый подпункт,
    *   второй подпункт.

#.  Второй пункт.

    #.  Первый подпункт.
    #.  Второй подпункт.

Текст, который идёт после списка.

После этого текста идёт список:

  1. Первый пункт.

    • первый подпункт,

    • второй подпункт.

  2. Второй пункт.

    1. Первый подпункт.

    2. Второй подпункт.

Текст, который идёт после списка.

Картинки#

Чтобы вставлять картинки в текст, есть две основные директивы image и figure. Они простые в использовании, о них можно прочитать в документации для RST.

Подробнее я хочу рассказать вам о более наглядной директиве — thumbnail. Она позволяет увеличить картинку при клике на неё прямо на странице сайта.

Чтобы директива thumbnail стала у вас работать, надо в файле conf.py в пункте extensions добавить расширение sphinxcontrib.images. Выглядеть это должно так:

extensions = ['sphinxcontrib.images',
]

После этого не забудьте сохранить файл conf.py и установить само расширение. В терминале введите команду:

pip3 install sphinxcontrib.images

Сама директива thumbnail в тексте может иметь следующий вид:

..  thumbnail:: _images/img.jpg
    :width: 300px
    :height: 100px
    :align: center
    :alt: Альтернативный текст для картинки
    :title: Описание для картинки
    :show_caption: True

  1. Сразу после объявления директивы, надо прописать путь в папке до самой картинки. В данном случае путь выглядит так:

    _images/img.jpg

  2. Это значит, что картинка лежит в папке _images и называется img.jpg

  3. Следующие две настройки отвечают за высоту и ширину картинки. width — ширина, height — высота.

  4. Align отвечает за размещение картинки на странице: center — центрирует картинку, right — размещает картинку по правой стороне, а left — по левой.

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

  6. Title — описание картинке, которое отображается прямо под ней.

  7. Show_caption — если не присвоить этой настройке значение True, то title не будет отображаться.

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

Note

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

.. thumbnail:: _images/img.jpg

Такая картинка тоже отобразится.

Прочее#

Я перечислил основные вещи из синтаксиса reStructuredText, но там ещё большое количество функционала и возможностей по настройке текста. При написании документации не забывайте обращаться к документации от Sphinx и Docutils.

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

Note

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