Повторное использование текста в RST для документации Sphinx

Question

Я пишу документацию в формате RST и генерирую HTML с помощью Sphinx.

Я хочу, чтобы иметь возможность написать абзац в RST-файле и повторно использовать тот же абзац в другом RST-файле в той же папке. Я хочу, чтобы повторное использование таким образом, что если я вношу изменения в исходный абзац, он должен автоматически изменяться во всех других файлах, на которые он ссылался, когда я генерирую HTML с помощью Sphinx.

Есть ли какой-либо синтаксис RST, чтобы это произошло? Любая помощь приветствуется.

Answer 1

Вы можете использовать include directive.

Для основной включают ссылки на пункт, который вы хотите повторно использовать следующим образом:

Some text 

.. include:: /path/to/file_to_include.rst 

More text 

В нашем примере, содержание file_to_include.rst является Included text. Sphinx сгенерирует:

Some text 

Included text 

More text 

Как вы можете увидеть в документации Docutils (связанный выше), вы можете дополнительно указать набор опций, например, чтобы ограничить входящий в текст в диапазоне строк.