Клавиатура reStructuredText онлайн: разметка для Sphinx
Заголовки подчёркиванием, директивы отступом: здесь отступ - часть синтаксиса.
Предпросмотр
Предпросмотр примерный: он показывает смысл разметки, а не то, как её нарисует конкретное приложение. Шрифты, цвета и отступы везде свои, а часть возможностей зависит от версии.
0 симв.
Что пишет каждая кнопка
| Действие | Синтаксис | Примечание |
|---|---|---|
| B | **bold** |
Жирный |
| I | *italic* |
Курсив |
| Code | ``code`` |
Код в строке - ДВЕ обратные кавычки, в отличие от Markdown |
| Title | Title
===== |
Заголовок - подчёркивание не короче текста |
| Section | Section
------- |
Раздел - другой символ означает другой уровень |
| List | - item |
Маркированный список |
| #. | #. item |
Список с автонумерацией |
| Code block | .. code-block:: python
code |
Блок кода - содержимое должно быть с отступом |
| note | .. note::
text |
Примечание - отступ входит в синтаксис |
| warning | .. warning::
text |
Предупреждение |
| Toctree | .. toctree:: |
Дерево оглавления - Sphinx |
| Link | `text <https://example.com>`_ |
Ссылка - обратите внимание на подчёркивание в конце |
| Ref | :ref:`label` |
Перекрёстная ссылка внутри документации - Sphinx |
Телефон собирает файл приложения - поэтому это дольше обычной загрузки.
Ищите этот значок: reStructuredText
Отступ здесь не оформление
В reStructuredText содержимое принадлежит директиве, потому что оно сдвинуто отступом. Без отступа блок перестаёт быть заметкой и становится абзацем с двумя двоеточиями, и видно это только после сборки документации. Кнопки на странице вставляют директивы сразу с правильным отступом.
Разметка документации Python
reStructuredText читает Sphinx, поэтому на нём написана документация большинства проектов на Python, Read the Docs и docstrings, из которых собирается справочник API. Формат строже Markdown: его делали для однозначного разбора, а не для быстрого набора.
У заголовка нет своего знака: строка становится заголовком, когда под ней строка знаков препинания не короче её. Всё сложнее выделения - директивы: две точки, имя, два двоеточия и содержимое с отступом.
Как пользоваться
- Вставляйте заголовки кнопками. Подчёркивание появится сразу и нужной длины.
- Держите содержимое директив с отступом. Три или четыре пробела, одинаково везде, и пустая строка после директивы.
- Скопируйте текст в файл .rst. Нажмите "Копировать всё", вставьте и соберите документацию для проверки.
Вопросы и ответы
Директива note выводится простым текстом. Почему?
Обычно нет отступа у содержимого или пустой строки между директивой и содержимым. Нужно и то и другое.
Какие символы брать для заголовков?
Любые знаки препинания, но одинаково по всему файлу. Часто берут = для названия, - для разделов и ~ для уровня ниже.
Почему код в двух обратных кавычках?
Одна обратная кавычка уже занята под интерпретируемый текст. Две дают буквальный текст, как одна в Markdown.
