我发现 ..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
最佳答案
在 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
orliteral
the common options:class:
and:name:
are recognized as well.Combining
start/end-line
andstart-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 包含指令 : ignore the header from included file,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/54518160/