时间戳

首页 > 解决方案 > Python Sphinx 包含指令：忽略包含文件中的标头

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

问题描述

我发现.. 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

标签： pythonpython-sphinxrestructuredtext

解决方案

在Sphinx 文档指令页面上，没有.. include::指令的详细信息，但有一个指向包含外部文档片段的链接。

发现指令有一些选项.. 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 codeor literalcommon options :class:and:name:也被认可。

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

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

查看raw已尝试的邻居指令，现在它可以工作了！

此代码包括part.rst第 5 行（在我的标题之后）

.. 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

推荐阅读