Include whole text sections from other *.rst - files into this file?

Question

I'm using Sphinx and I want to "copy" over a given section from one *.rst file into multiple other ones automatically, so that when I adapt the text section in the first file the changes are automatically reflected in the copied parts of the other files.

E.g.:

base.rst:

This is a section/paragraph I want to see in other *.rst - files.

derivate.rst:

Here is some text. But the following paragraph should be the paragraph from above ^^:

<that paragraph from above>

Here the file continues.

How can I do that with Sphinx and reStructuredText?

Lining

Answer 1

Use the include directive.

Here is some text. But the following paragraph should be the paragraph from above ^^:

.. include:: base.rst

Here the file continues.

Dehypnotize

Thanks but that copies the whole thing.. What if I only need a specific section from base.rst? – Lining

Put that section into its own file, then include it both in base.rst and derivate.rst. – Dehypnotize

The include directive has several options that can be used to include specific parts of a document. See https://mcmap.net/q/1328460/-python-sphinx-include-directive-ignore-the-header-from-included-file/407651. – Prosenchyma

@Prosenchyma the disadvantage is if you edit the included file, you need to update all the places where it gets included, so I avoid that usage. It's good for literalinclude where you can specify a Python object, or where markers are used for start and end. I think one snippet per file is easier to manage. – Dehypnotize

Thanks @Prosenchyma I managed to do it with ..include: <file> and :start-line: 2, :end-line: 4. – Lining