About includes

Summary

include

include is a directive that comes with Docutils. It allows inclusion of text as if it were written at that point.

literalinclude

literalinclude is a directive known by Sphinx. It is used to show source code.

Both directives represent a potential security hole. That is why some sites permanently disallow them by means of the Docutils "file_insertion_enabled" setting. We don't do that, but apply an include-files-check instead.

Enabled!

① In the container both the .. include:: and the .. literalinclude:: directive are enabled.

② A source code check will ensure that only project files can be included. It signals alarm for all lines that look like a real include.

③ Administrators can turn the include file check off.

Relative paths

Consider a project with this file structure:

Project
├── Classes
│   └── Helpers
│       └── GetDoc.php
├── Documentation           <-- base dir of documentation
│   ├── Chapter-1.rst
│   └── Includes.rst.txt

In the file Chapter-1.rst we can use these relative file specs:

.. include:: Includes.rst.txt

.. literalinclude:: ../Classes/Helpers/GetDoc.php

Absolute paths

New in version v2.4.0.

If the included files are specified as absolute paths they are considered to be starting at the base dir of documentation which currently is configured to be Project/Documentation. Absolute paths are secure. They can never target files beyond the basedir.

Tip

You may now write .. include:: /Includes.rst.txt in any ReST file you have, no matter how deep it's buried in the hierarchy.

This means: You don't have to tweak the include when you move files around!

Relative paths are being surveilled

Absolute paths are secure.

Relative paths represent a potential security hole.

They can address files that are external to the project. For example, the following include may show a result you probably wouldn't wish to see in the final html in the web:

..␠include:: ../../../../../etc/passwd

As a countermeasure the container checks all include paths. If a file from outside the project is referenced the rendering will be aborted. No output will be produced. A message is shown on stdout in the terminal window though.

Attention

The include-file-check may run into false alarms as it only does a rough lexical analysis and not fully parses the reST code for speed reasons. So we have to disguise the include directive in the above code example by writing ..␠include:: instead of .. include::. Otherwise the example would prevent the manual from being rendered because that line looks like a real include directive, although it would never be executed.

Projectwide includes

New in version v2.4.0.

All files in the project can be referenced with relative path specifications.

All files in and below the base dir of documentation can be referenced with absolute path specifications.

base dir of documentation currently is Project/Documentation. If possible, this may be changed in future to Project/.

Allow systemwide includes

The administrator can turn include file checking OFF in jobfile.json like so:

{
  "tctconfig": {
     "disable_include_files_check": 1
  }
}

In that case any file reachable by a relative path can be included, no matter if it belongs to the project or not.