4

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?

mzjn
  • 48,958
  • 13
  • 128
  • 248
glades
  • 3,778
  • 1
  • 12
  • 34

1 Answers1

4

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.
Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • 1
    Thanks but that copies the whole thing.. What if I only need a specific section from base.rst? – glades Nov 13 '21 at 10:07
  • 1
    Put that section into its own file, then include it both in base.rst and derivate.rst. – Steve Piercy Nov 14 '21 at 03:41
  • 1
    The `include` directive has several options that can be used to include specific parts of a document. See https://stackoverflow.com/q/54518160/407651. – mzjn Nov 14 '21 at 06:47
  • @mzjn 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. – Steve Piercy Nov 15 '21 at 02:34
  • Thanks @mzjn I managed to do it with ..include: and :start-line: 2, :end-line: 4. – glades Nov 17 '21 at 21:23