restructuredtext - Include arbitrary files in RST

Question

The DocUtils include directive allows the inclusion of arbitrary text into an RST document. The problem is that the implementation restricts the specified files to be in the same document as is the location of the included file. This makes the use of includes for external files that may be used in many documents difficult. The standard DocUtils solution is to use something called Standard Definition Files. Unfortunately, these require anyone using this facility to have the DocUtils source code involved which will affect every end-user who needs this facility. Needing source code is not an acceptable solution for people who are not programmers and are only trying to use Docutils, possibly in an environment such as Sphinx. Is there any other work-around for this situation?

Can you cite your references with links? Does Sphinx's literalinclude directive do what you need? — Steve Piercy
@Steve Piercy, What references do you want? I checked literalinclude and it suffers from the same problem as include. It can only retrieve a file from the current document whereas I want to retrieve a file from an arbitrary location in the file system. — Jonathan
Would something like this help? pypi.org/project/sphinxcontrib-remoteliteralinclude — mzjn

Steve Piercy Steve Piercy · Accepted Answer · 2020-04-30T18:53:34

Use literalinclude directive using .. to navigate up and around the filesystem. For example:

.. literalinclude:: ../../external-to-project-directory/src/somefile.py

Will include somefile.py as literal code into your documentation.

If you want to parse the code as rst, then use include instead.

restructuredtext - Include arbitrary files in RST

1 Answers