Including files

Includes can be used for two use cases in the documentation: Repeating text snippets used in several places or breaking up long pages into easier to edit subparts.

Some documentation projects have the same snippet of text appear in several places. This text can be maintained once and included in many places.

In this case it may make sense to include text snippets. The .. include:: someFile.rst.txt directive does this.

Files to be included cannot lie outside the Documentation folder. They may not end on .rst. By convention they should end on .rst.txt.

Table of contents

Example of a simple include:

Include the same text asking for contributions in all Events that do not have an example yet:

Documentation/Events/Event1.rst

Example
=======

..  include:: /_includes/EventsContributeNote.rst.txt

Documentation/Events/SomeOtherEvent.rst

Example
=======

..  include:: /_includes/EventsContributeNote.rst.txt

The file to be included:

Documentation/_includes/EventsContributeNote.rst.txt

..  note::
    Currently, we do not have an example for this event. If you can provide a
    useful one, please open an issue ...

These rst definitions will be included in all places the include is used as if they had been written directly into the rst file. All markup is respected.

Example: Break up a large file into manageable pieces

In places like the TSconfig reference or TCA reference it is helpful to display all properties of an element on one page. However this gives the contributors very large rst files to maintain. Such files can be broken into pieces that contain only the definition and maybe example of one parameter each.

Documentation/ColumnsConfig/Type/Category/Index.rst

Properties of the TCA column type `category`
============================================

..  confval-menu::
    :display: table
    :type:
    :Scope:

    ..  include:: _Properties/_Default.rst.txt
        :show-buttons:

    ..  include:: _Properties/_ExclusiveKeys.rst.txt
        :show-buttons:

    ..  include:: _Properties/_ForeignTable.rst.txt
        :show-buttons:

Each include file in turn contains the complete data for one property, for example:

Documentation/ColumnsConfig/Type/Category/_Properties/_ExclusiveKeys.rst.txt

..  _columns-category-properties-exclusivekeys:

..  confval:: exclusiveKeys
    :name: category-exclusiveKeys
    :type: string (list of)

    List of keys that exclude any other keys ...

The option :show-buttons: display a special "Edit on GitHub" button only for the section contained within include:

Properties

Name	Type	Scope
[content]	string, local file path, relative or absolute
:show-buttons:	string, local file path, relative or absolute

[content]

Type: string, local file path, relative or absolute

Path to the file to be included. Can be relative or absolute.

..  include:: /some/absolute/path/_includes/_SomeFile.rst.txt

..  include:: ../_includes/_SomeFile.rst.txt

The path is calculated starting from the Documentation directory. It is not possible to include files from different locations in an extension.

:show-buttons:

Type: string, local file path, relative or absolute

If set an edit on GitHub Button is displayed if the edit-on-github workflow is enabled in the guides.xml. In future other buttons might be displayed if configured in the guides.xml.