在Python Sphinx图像指令中使用环境变量

Question

我有一个带有Sphinx文档的Python项目，为了保持代码库的小，我想要包含在文档中的一些图像和其他文件位于一个单独的仓库中。

对于Sphinx docs build，我确实有一个shell环境变量设置为指向另一个repo。我试过像image directive这样使用它：

.. image:: $OTHER_REPO/docs_images/image.png

但这不起作用。

现在，我已经在docs/conf.py中放了一些代码，将我需要的文件复制到docs源代码树中，然后就可以了。但这感觉就像一个黑客，必须有一个适当/更好的方法来做到这一点？

Answer 1

我发现以下解决方案可以解决我的问题。

访问Change variable in sphinx conf.py as part of build command

基本上，我们可以在 ma​​ke.bat 文件中通过设置以下注释来定义 Jupyter 中可以初始化的 env 变量：

Jupyter 笔记本：

try:
    status_flag = %env status_flag
    print('Status_flag defined as ' + status_flag + '!')
    
except:
    status_flag = 'MP4'
    print('Status_flag defined as ' + status_flag + '!')

make.bat：

SET status_flag=HTML
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

Answer 2

在conf.py中，您可以设置名为rst_epilog的变量。使用replacement directive你可以做到这一点。

在conf.py：

中

rst_epilog = """
.. |other_repo| """ + os.environ['OTHER_REPO'] + """
"""

在实际文件中：

.. image:: |other_repo|/docs_images/image.png

我没有测试过，但可能是一个起点。