reStructuredText：包含文件时修复部分/标题级别

Question

我有几十个

.rst

文件，它们都是通过

index.rst

从主

.. include: file.rst

文件加载的。

现在我想重组目录并将一些文件移动到不同的标题级别 - 但不想更改所有文件中的所有标题级别。

主文件的节级别为 1，所有包含的文件都使用节级别 2。我想在主文件中引入一些 2 级标题，并将 2 级标题的文件作为 3 级包含，而不实际更改其文件内容（也有许多文件）。

包含文件时我可以以某种方式“修复”或更改部分级别吗？

示例

旧结构

• 主标题
  • 文件1标题
  • 文件2标题

index.rst

：

Main title
==========

.. include: file1.rst
.. include: file2.rst

file1.rst

：

File1 title
-----------

Content

新结构

• 主标题
  • 字幕
    • 文件1标题
  • 文件2标题

index.rst

：

Main title
==========

Subtitle
--------
.. include: file1.rst
   :FIXMEsomeOptionToChangeSectionLevels:

.. include: file2.rst

Answer 1

默认情况下，“include”会将要包含的rST文件的内容插入到输入流中，然后继续解析。因此，对于解析器来说，一个大的输入文档没有区别。 没有“神奇”的选项可以重写之前的章节标题装饰 将文件插入输入流。

但是，由于装饰风格与节级别没有固定的关系，所以最多需要适配一半的包含文件： 如果超过一半的文件应移至较低级别，您可以为第二级别引入新的装饰。如果所有文件都向下移动一级， 只需要更改主文档。例如：

新结构

• 主标题
  • 字幕
    • 文件1标题
    • 文件2标题
  • 第二个字幕
    • 文件3标题

Main title
==========

Subtitle with a hithero not used adornment style
`````````````````````````````````````````````````
.. include: file1.rst
.. include: file2.rst

second subtitle
```````````````
.. include: file3.rst

...

---

还有一个使用“include”指令的临时“解析器”选项的实验性解决方法。虽然它旨在包含其他输入格式（markdown、Docutils-XML）的文件，但它也可以与 reStructuredText 解析器一起使用：

Subtitle
--------
.. include: file1.rst
   :parser: rst

在这种情况下，包含的文件被解析为“虚拟文档”，其子元素被附加到主文档树中。

警告：

• 将“include”与“parser”选项一起使用可能会生成无效的文档结构并导致未指定的行为或奇怪的错误！
• “虚拟文档”中的命名空间与主文档之间的关系未指定，并且可能在未来版本中发生变化。