0

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?

Jonathan
  • 2,635
  • 3
  • 30
  • 49
  • 1
    Can you cite your references with links? Does Sphinx's [`literalinclude` directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude) do what you need? – Steve Piercy Apr 29 '20 at 23:27
  • @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 Apr 30 '20 at 09:25
  • Would something like this help? https://pypi.org/project/sphinxcontrib-remoteliteralinclude/ – mzjn Apr 30 '20 at 14:45

1 Answers1

0

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.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • Steve Piercy, the documentation for `literalinclude` includes the following statement: `The file name is usually relative to the current file’s path. However, if it is absolute (starting with /), it is relative to the top source directory`. This implies to me that the document being included must be in the document directory hierarchy. Am I wrong in my interpretation? – Jonathan May 01 '20 at 15:35