Sphinx inline include

Question

Я хочу использовать встроенную функцию .. include::, но я могу получить ее, чтобы фактически включить файл, который я хочу, если я отделяю его двумя новыми строками из предыдущего текста.

Прежде, чем кто-либо спросит, файл, который я хочу включить, является номером протокола, поэтому нет, он вообще не использует новую строку. Я хочу иметь возможность легко изменить его, чтобы я мог использовать его в нескольких местах моей документации. Я предполагаю, что примером будет «В настоящее время мы используем протокол (proto.txt)». Я новичок в Sphinx и rst, поэтому, возможно, есть очень очевидное решение, которого я не нашел.

Answer 1

Внутренние соединения с Sphinx невозможны.

Однако, вы можете определить глобальныхaliases в rst_epilog переменных вашем build configuration file.

Например, вы можете добавить следующие строки в файл conf.py:

rst_epilog = """ 
    .. |version| replace:: 4.1 
    .. |protocol| replace:: httpx 
""" 

Теперь вы можете получить доступ к переменным |version| и |protocol| из любого .rst файла в пределах вашего проекта, например, как это:

Version |version| uses the |protocol| protocol.

становится

Version 4.1 uses the httpx protocol.

Если другие части вашего программного обеспечения требуют указать (или другие переменные), которые должны быть указаны в определенном файле или формате, вы можете написать скрипт, чтобы прочитать его там как переменную в конфигурационный файл Sphinx.