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::指令有一些选项

可以识别以下选项：
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配置设置。

使用code或literal可以识别公用选项:class:和:name:   也是

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

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

尝试查看邻居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 include指令：忽略包含文件中的标头

1 个答案: