Python Sphinx 包含指令 : ignore the header from included file

Question

我发现 ..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 – Include content based on configuration ，我可以用

包装标题

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

Answer 1

在 Sphinx documentation Directives page .. include:: 指令没有详细信息，但有一个指向 Including an External Document Fragment 的链接.

发现..include::指令有一些options

The following options are recognized:

start-line : integer 

Only the content starting from this line will be included. (As usual in Python, the first line has index 0 and negative values count from the end.)

end-line : integer 

Only the content up to (but excluding) this line will be included.

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

Only the content after the first occurrence of the specified text will be included.

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

Only the content before the first occurrence of the specified text (but after any after text) will be included.

literal : flag (empty) 

The entire included text is inserted into the document as a single literal block.

code : formal language (optional)

The argument and the content of the included file are passed to the code directive (useful for program listings). (New in Docutils 0.9)

number-lines : [start line number] 

Precede every code line with a line number. The optional argument is the number of the first line (defaut 1). Works only with code or literal. (New in Docutils 0.9)

encoding : name of text encoding 

The text encoding of the external data file. Defaults to the document's input_encoding.

tab-width : integer 

Number of spaces for hard tab expansion. A negative value prevents expansion of hard tabs. Defaults to the tab_width configuration setting.

With code or literal the common options :class: and :name: are recognized as well.

Combining start/end-line and start-after/end-before is possible. The text markers will be searched in the specified lines (further limiting the included content).

但没有示例如何使用此语法。

查看邻居 raw 指令尝试过，现在可以了!

此代码包括第 5 行(在我的标题之后)的 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