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

Question

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

对于 Sphinx 文档构建，我确实设置了一个 shell 环境变量来指向另一个存储库。我尝试从 image 指令 使用它，如下所示：

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

但这行不通。

现在，我在

docs/conf.py

中放入了一些代码，将我需要的文件复制到

docs

源树中，然后它就可以工作了。但这感觉就像一个黑客，一定有一个正确/更好的方法来做到这一点？

Answer 1

我找到了以下解决方案来解决我的问题。

访问 更改 sphinx conf.py 中的变量作为构建命令的一部分

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

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

我知道这个问题已经被问了 7 年多了，但最近几天我遇到了同样的问题并解决了如下问题。也许它会在未来帮助其他人

长话短说：在conf.py中使用rst_prolog进行替换

• https://docutils.sourceforge.io/docs/ref/rst/restructedtext.html#substitution-definitions
• https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_prolog

示例

让我们假设以下项目目录：

ROOT
|-docs
|   |-dummy_pic.png
|-docs_sphinx
|   |-source
|       |-conf.py
|-dummy_pkg
    |-test_module.py

将以下设置添加到conf.py (rst_prolog)

import os
# get root path
ROOT = os.path.abspath(os.path.dirname(__file__))
# set docs folder
docs_folder = os.path.abspath(os.path.join(ROOT, "..", "..", "docs"))
# set dummy path and update slashes
dummy_png = os.path.join(docs_folder, "dummy_pic.png")
dummy_png = dummy_png.replace("\\", "/")

# set rst_prolog
# define absolute file path --> based on https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-rst_epilog
rst_prolog = f"""
.. |dummy_png| image:: {dummy_png} 
    :height: 11
""" 

然后，在文档字符串中使用替换。在本例中，它位于 test_module.py

def test_func():
    '''
    |dummy_png|
    '''
    pass

这应该可以解决问题。至少它解决了我的问题。此外，我想尝试它是否也适用于其他文件。