What is the sphinx directive for including a document into another document?

问题

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.

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.

Hopefully it's similar to this NON WORKING EXAMPLE:

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

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

回答1:

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.

Full documentation can be found in the docutils reStructuredText reference (#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

来源：https://stackoverflow.com/questions/38880277/what-is-the-sphinx-directive-for-including-a-document-into-another-document

标签

python

python-sphinx

restructuredtext