问题描述
我发现 ..include:: 指令对于文本重用非常有用:相同的部分可以插入到不同的文档中.
I found .. include:: directive very useful for text reuse: the same parts could be inserted in different documents.
但是标题级别存在问题.
But there is a problem with header levels.
例如，如果我有带有二级标题的 part.rst
For example, if I have part.rst with second level header
part.rst
Header level 2
----------------
My text to be included
并将其包含在具有各种标题级别的不同文档中
and include it in the different documents with various header levels
doc 1
Header level 1
================
.. include:: part.rst
doc2
Header level 2
----------------
.. include:: part.rst
doc 3
Header level 3
~~~~~~~~~~~~~~~~~
.. include:: part.rst
永远都是2级，控制不了.
It will be always the same level 2. Can't control it.
我已经阅读了关于 sphinx.ext.ifconfig – 包含基于配置的内容，我可以用
I've read about sphinx.ext.ifconfig – Include content based on configuration, I could wrap the headers with
part.rst
.. ifconfig:: hide_part_rst_title
Header level 2
----------------
My text to be included
但是看起来在很多零件文件的情况下创建了很多变量.
But it looks like to create many variables in case of many parts files.
可能有更优雅的方式吗?
May be is there a more elegant way?
如何在没有原始标题的情况下包含 .rst 文件?如果我裁剪这个，我可以像这样在每个地方添加一个标题
How to include the .rst files without original headers? If I crop this I could add a header in each place like this
.. 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
推荐答案
Sphinx 文档指令页面没有关于 ..include:: 指令的详细信息，但有一个指向 包括外部文档片段.
On the Sphinx documentation Directives page there are no details for .. include:: directive, but there is a link to Including an External Document Fragment.
发现..include::指令有一些选项
识别以下选项:
start-line : integer
只有从这一行开始的内容才会是包括.(像往常一样在 Python 中，第一行的索引为 0 和负数值从最后开始计数.)
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)
参数和被包含文件的内容被传递给代码指令(对程序列表有用).(Docutils 0.9 中的新功能)
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]
在每一行代码前加上一行数字.可选参数是第一行的编号(默认1).仅适用于代码或文字.(Docutils 0.9 中的新功能)
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
外部数据文件的文本编码.默认为文档的 input_encoding.
The text encoding of the external data file. Defaults to the document's input_encoding.
tab-width : integer
硬制表符扩展的空格数.负值阻止扩展硬标签.默认为 tab_width 配置设置.
Number of spaces for hard tab expansion. A negative value prevents expansion of hard tabs. Defaults to the tab_width configuration setting.
使用 code 或 literal 可以识别常用选项 :class: 和 :name:
With code or literal the common options :class: and :name: are recognized as well.
组合 start/end-line 和 start-after/end-before 是可能的.这将在指定行中搜索文本标记(进一步限制包含的内容).
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 指令已尝试，现在可以使用了！
Looking at neighbour raw directive tried and now it works!
此代码包含第 5 行(在我的标题之后)的 part.rst
This code includes the part.rst from the 5th line (after my heading)
.. include:: part.rst
:start-line: 5
或者如果修改part.rst添加一个特殊标签
or if modify part.rst addind a special label
Header level 2
----------------
.. include_after_this_label
My text to be included
我可以在多个文件中使用相同的标签来灵活地包含文件
I could use the same label in multiple files to include the file flexible
.. include:: part.rst
:start-after: .. include_after_this_label
这篇关于Python Sphinx 包含指令:忽略包含文件中的标头的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！