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