Python Sphinx 包含指令：忽略包含文件中的 header

Question

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

但是 header 关卡有问题。

例如，如果我有 part.rst 二级 header

part.rst

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

My text to be included

并将其包含在具有各种 header 级别的不同文档中

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，我可以用

包裹 header

part.rst

.. ifconfig:: hide_part_rst_title

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

My text to be included

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

可能有更优雅的方式吗？

如何在没有原始 header 的情况下包含 .rst 个文件？如果我裁剪这个我可以在每个地方添加一个 header 像这样

.. 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 there are no details for .. include:: directive, but there is a link to Including an External Document Fragment.

发现.. include::指令有一些选项

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

Python Sphinx 包含指令：忽略包含文件中的 header

Python Sphinx include directive: ignore the header from included file

python

restructuredtext

python-sphinx