将文档包含到另一个文档中的 sphinx 指令是什么? [英] What is the sphinx directive for including a document into another document?

问题描述

在我的文档中，我有一个 examples 目录，我可以说，

In my documentation I have an examples directory where I can say,

.. literalinclude:: examples/1_basic_usage.py
   :language: python
   :linenos:

..效果很好，因为它们是代码，并且格式正确地为代码.

..which works great, because they're code and they're formatted correctly as code.

但是，我想对非代码文档执行 literalinclude.在整个项目级别，我已经定义了 AUTHORS、DESCRIPTION、ATTRIBUTION 等，我想(基本上)将它们粘贴到-place 但我不知道怎么做.

However, I want to do a literalinclude on non-code documents. At the entire-project level I already have AUTHORS, DESCRIPTION, ATTRIBUTION, etc. defined, and I want to (essentially) paste them in-place but I don't know how.

希望它类似于这个非工作示例:

Authors
-------
.. literalinclude:: ../../AUTHORS

Attribution
-----------
.. literalinclude:: ../../ATTRIBUTION

推荐答案

显然，使用 .. include:: <path> 指令可以做到这一点.

Apparently the way to do this is with the .. include:: <path> directive.

这在他们的文档中并不明显，而且根本没有示例存根.

It's no-where obvious in their documentation and doesn't have an example stub at all.

完整文档可以在 docutils reStructuredText 参考 (#include).

Full documentation can be found in the docutils reStructuredText reference (#include).

include"指令读取文本文件.指令参数是要包含的文件的路径，相对于包含指令的文档.除非给出选项文字或代码，否则文件将在指令点的当前文档上下文中解析.例如:

The "include" directive reads a text file. The directive argument is the path to the file to be included, relative to the document containing the directive. Unless the options literal or code are given, the file is parsed in the current document's context at the point of the directive. For example:

第一个示例将在文档级别进行解析，并且可以因此包含任何构造，包括节标题.

This first example will be parsed at the document level, and can thus contain any construct, including section headers.

.. include:: inclusion.txt

Back in the main document.

   This second example will be parsed in a block quote context.
   Therefore it may only contain body elements.  It may not
   contain section headers.

   .. include:: inclusion.txt

这篇关于将文档包含到另一个文档中的 sphinx 指令是什么?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！