Полное руководство по отступам директив reStructuredText

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

Вот разбор правильных правил отступов:

.. my_markup:: arg1
               arg2_must_go_here_because_of_arg1_indentation
               arg3_must_go_here_etc
     :option_whose_indentation_does_not_matter: val1
     :option2_must_go_here_because_of_option1_indentation: val2
     :option3_must_go_here_etc: val3

     Content must be indented the same as options when present
     and maintain consistent indentation throughout

Содержание

• Базовая структура директивы
• Отступы аргументов директивы
• Отступы параметров директивы
• Отступы содержимого директивы
• Специальные случаи и распространенные ошибки
• Полные примеры

Базовая структура директивы

Директива reStructuredText состоит из четырех основных компонентов в определенном порядке:

1. Маркер директивы (всегда в одной строке)
2. Аргументы директивы (необязательные)
3. Параметры директивы (необязательные, в формате списка полей)
4. Содержимое директивы (необязательное)

В документации Sphinx подчеркивается, что “синтаксис RST чувствителен к отступам” и что компоненты должны следовать этой последовательности для корректного разбора.

Отступы аргументов директивы

Ваше понимание отступов аргументов в основном верно:

• Аргументы могут быть разделены пробелами в той же строке, что и маркер директивы
• Аргументы могут продолжаться в следующих строках
• Первый аргумент задает прецедент для последующих аргументов
• Аргументы должны иметь последовательные отступы после установления прецедента

.. my_markup:: argument1
               argument2_continuation
               argument3_continuation

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

Отступы параметров директивы

Ваше понимание отступов параметров верно:

• Параметры должны быть указаны в строке, непосредственно следующей за маркером или последним аргументом
• Первый параметр не требует определенного отступа (кроме ненулевого)
• Последующие параметры должны быть отступлены на том же уровне, что и первый параметр

На Stack Overflow подтверждается: “Первый параметр не требует определенного отступа (кроме ненулевого) и задает прецедент для последующих параметров”.

Отступы содержимого директивы

Вот где ваше понимание требует исправления:

• Содержимое всегда должно следовать после пустой строки после последнего параметра или аргумента
• Содержимое всегда должно иметь последовательные отступы - это относится даже к случаям, когда параметры отсутствуют
• Когда параметры присутствуют, содержимое должно быть отступлено на том же уровне, что и параметры
• Когда параметры отсутствуют, содержимое все равно нуждается в последовательных отступах (не “в любом ненулевом количестве”)

Как указано в документации Sphinx: “Содержимое директивы следует после пустой строки и отступлено относительно начала директивы, или если параметры присутствуют, на том же уровне, что и параметры”.

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

Специальные случаи и распространенные ошибки

Директивы со смешанным содержимым

Некоторые директивы, такие как code-block, имеют конкретные требования форматирования:

.. code-block:: python
   :linenos:

   def hello():
       print("Hello, world!")

Правила прецедента отступов

• Первая строка любого компонента задает стандарт для последующих строк
• Нулевой отступ (без пробелов) для строки компонента обычно недопустим
• Непоследовательные отступы внутри компонента вызовут ошибки разбора

Параметры в формате списка полей

Параметры должны следовать синтаксису списка полей с двоеточиями:

.. directive:: arg
   :option1: value1
   :option2: value2

Полные примеры

Пример 1: С аргументами и параметрами (Правильно)

.. my_markup:: arg1
               arg2_continuation
     :option1: value1
     :option2: value2

     Content indented same as options
     Maintains consistent indentation

Пример 2: Только с аргументами (Пример 3 пользователя - Исправлено)

.. my_markup:: arg1 arg2
               arg3_continuation

     Content must be indented consistently
     Cannot use "any nonzero amount" arbitrarily
     Must maintain the same indentation throughout

Пример 3: Только параметры (Отсутствовал в примерах пользователя)

.. my_markup::
     :option1: value1
     :option2: value2

     Content indented same as options
     Consistent indentation required

Пример 4: Только содержимое (Отсутствовал в примерах пользователя)

.. my_markup::

     Content must be indented consistently
     Cannot start at column 1 (no indentation)
     Must maintain same indentation throughout

В спецификации reStructuredText подтверждается, что “блок директивы разделен на аргументы, параметры (список полей) и содержимое (в этом порядке), из которых каждое может присутствовать”. Этот структурированный подход обеспечивает последовательный разбор в различных реализациях Sphinx.

Источники

1. reStructuredText Primer — Sphinx documentation
2. Clarification on reStructuredText directive indentation rules - Stack Overflow
3. reStructuredText Directives - docutils.sourceforge.io
4. reStructuredText markup - Python Developer Guide
5. Restructured Text (reST) and Sphinx CheatSheet

Заключение

На основе результатов исследования, вот основные выводы относительно правил отступов для директив reStructuredText:

1. Структура директивы строгая: Аргументы → Параметры → Содержимое, в этом конкретном порядке
2. Аргументы: Могут продолжаться в последующих строках с последовательными отступами, основанными на первом аргументе
3. Параметры: Должны быть списками полей с двоеточиями, первый параметр задает прецедент для последующих параметров
4. Содержимое: Всегда требует последовательных отступов, даже когда параметры отсутствуют
5. Пустые строки важны: Разделяют маркер директивы от содержимого, а параметры/содержимое от предыдущих элементов

Ваши примеры 1 и 2 верны, но пример 3 неверен, потому что содержимое не может использовать “любое ненулевое количество” отступов произвольно - оно должно быть последовательным независимо от наличия параметров. Правило таково: отступы содержимого всегда последовательны, никогда не произвольны.

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