Python Sphinx include 指令：忽略包含文件中的标头

I found .. include::指令对于文本重用非常有用：相同的部分可以插入到不同的文档中。

但标题级别存在问题。

例如，如果我有part.rst带有二级标题

part.rst

Header level 2
----------------

My text to be included

并将其包含在具有不同标题级别的不同文档中

doc 1

Header level 1
================

.. include::  part.rst

doc2

Header level 2
----------------

.. include::  part.rst

doc 3

Header level 3
~~~~~~~~~~~~~~~~~

.. include::  part.rst

永远都是同样的2级。无法控制。

我读过关于sphinx.ext.ifconfig – 根据配置包含内容，我可以用以下内容包装标题

part.rst

.. ifconfig:: hide_part_rst_title

    Header level 2
    ----------------

My text to be included

但在零件文件很多的情况下，看起来会创建很多变量。

也许有更优雅的方式吗？

如何包括.rst没有原始标头的文件？如果我裁剪它，我可以在每个地方添加一个标题，如下所示

.. doc 1
Header level 1
================

Included text header
---------------
.. include::  part.rst

.. doc 2
Header level 2
----------------

Included text header
======================
.. include::  part.rst

.. doc 3
Header level 3
~~~~~~~~~~~~~~~~~

Included text header
~~~~~~~~~~~~~~~~~~~~~~~
.. include::  part.rst

On the Sphinx 文档指令页面没有详细信息.. include::指令，但有一个链接包括外部文档片段.

发现有一些options for .. include::指示

可以识别以下选项：

start-line : integer 

只有从这一行开始的内容才会被 包括。 （和 Python 中一样，第一行的索引为 0 和负数 值从末尾开始计算。）

end-line : integer 

仅内容最多 （但不包括）这一行将被包括在内。

start-after : text to find in the external data file

仅包含指定文本第一次出现之后的内容。

end-before : text to find in the external data file

仅包含第一次出现之前的内容 将包含指定的文本（但在任何后续文本之后）。

literal : flag (empty) 

整个包含的文本被插入到 文档作为单个文字块。

code : formal language (optional)

参数和包含文件的内容被传递到 代码指令（对于程序列表有用）。 （Docutils 0.9 中的新增功能）

number-lines : [start line number] 

在每个代码行前面添加一行 数字。可选参数是第一行的行号（默认 1）。仅适用于代码或文字。 （Docutils 0.9 中的新增功能）

encoding : name of text encoding 

外部数据文件的文本编码。 默认为文档的 input_encoding。

tab-width : integer 

硬选项卡扩展的空格数。负值会阻止扩展 硬标签。默认为tab_width配置设置。

With code or literal常见选项:class: and :name:被认可 以及。

组合start/end-line and start-after/end-before是可能的。这 文本标记将在指定行中搜索（进一步限制 包含的内容）。

but 没有例子如何使用这个语法。

看着邻居raw指令已尝试，现在可以了！

该代码包括part.rst从第五行开始（在我的标题之后）

.. include::  part.rst
    :start-line: 5

或者如果修改part.rst添加特殊标签

Header level 2
----------------
.. include_after_this_label

My text to be included

我可以在多个文件中使用相同的标签来灵活地包含文件

.. include::  part.rst
    :start-after: .. include_after_this_label