关于reStructuredText指令缩进规则的确认请求

我正在使用Sphinx工具将reStructuredText（rst）文档转换为HTML格式，已查阅Sphinx的rST入门指南及Docutils的rST文档，现需确认我对指令缩进规则的理解是否正确。

rST指令的组成 #

rst的「指令」由以下部分组成：

1. 指令标记：以显式标记起始符..开头，后跟指令类型、两个冒号及空格；
2. 指令参数；
3. 指令选项；
4. 指令内容。

我对缩进规则的理解 #

1. 指令标记必须单独占一行；
2. 指令参数可与标记同行以空格分隔，也可在标记下一行续写：
   • 若首个参数与标记同行，则后续参数需遵循其缩进；
   • 若首个参数在标记下一行，只需非零缩进，且后续参数遵循此缩进；
3. 指令选项需紧跟标记或最后一个参数的下一行：
   • 首个选项只需非零缩进，后续选项需遵循此缩进；
4. 指令内容需位于最后一个选项、最后一个参数或标记（以适用者为准）之后的空行的下一行：
   • 若有指令选项，内容缩进需遵循选项的缩进；
   • 若无选项，首行内容只需非零缩进，后续内容遵循此缩进。

以上理解是否正确？以下为示例说明我的理解：

示例1 #

.. 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

     I think this line of directive content must be indented the same as the options.
     I think this and subsequent lines of directive content must be indented the ...
     same as the first line of directive content

示例2 #

.. my_markup:: arg1 arg2
               arg3_must_go_here_because_of_arg1_indentation
    :option_whose_indentation_does_not_matter: val1
    :option2_must_go_here_because_of_option1_indentation: val2
    :option3_must_go_here_etc: val3

    I think this line of directive content must be indented the same as the options.
    I think this and subsequent lines of directive content must be indented the ...
    same as the first line of directive content.

示例3 #

.. my_markup:: arg1 arg2
               arg3_must_go_here_because_of_arg1_indentation

          I think this line of directive content can be indented any nonzero amount.
          I think this and subsequent lines of directive content must be indented ...
          the same as the first line of directive content.

结论 #

你的理解完全正确，和Docutils定义的rST指令缩进规则完全匹配：

• 指令标记独占一行是rST语法的硬性要求；
• 参数续写时，只要保持与首个续行参数的缩进对齐即可，无论参数是与标记同行还是换行书写；
• 选项的首个缩进只需非零，后续选项统一对齐该缩进即可；
• 内容必须在空行之后开始，有选项时对齐选项的缩进，无选项时首行只要非零缩进，后续内容对齐首行即可。

你的示例也准确体现了这些规则，没有问题。

内容的提问来源于stack exchange，提问作者StoneThrow