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

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

   Thissecondexamplewillbeparsedinablockquotecontext.
   Thereforeitmayonlycontainbodyelements.  Itmaynotcontainsectionheaders.

   .. include:: inclusion.txt