Use kernel-include in reST documents

The kernel-include reST-directive is a replacement for the include directive. The kernel-include directive expand environment variables in the path name and allows to include files from arbitrary locations.

Hint

Including files from arbitrary locations (e.g. from /etc) is a security risk for builders. This is why the include directive from docutils prohibit pathnames pointing to locations above the file-system tree where the reST document with the include directive is placed.

Substrings of the form $name or ${name} are replaced by the value of environment variable name. Malformed variable names and references to non-existing variables are left unchanged.

.. _media_header:

****************************
Media Controller Header File
****************************

.. kernel-include:: $BUILDDIR/media.h.rst

Since the kernel-include reST-directive is a replacement for the existing include directive, the options are the same, see reST include directive.