检查 Sphinx 文档是否调用了脚本答案

【问题标题】：Check if Sphinx doc called the script检查 Sphinx 文档是否调用了脚本
【发布时间】：2014-01-17 14:04:27
【问题描述】：

我目前正在尝试为使用 ArcGIS arcpy 库的脚本生成 sphinx 文档。

当 sphinx 在生成文档时尝试运行脚本时遇到问题，因为 arcpy 脚本从 arcgis gui 获取输入参数。由于 sphinx 是在没有 gui 的情况下调用脚本，因此这些参数为空并导致 Tracebacks，例如：

C:\VersionControl\PythonScripts\Source\src\_build\script_export_pdf.rst:4: WARNING:     autodoc: failed to import module u'gis.scripts.script_export_pdf'; the following exception was raised:
Traceback (most recent call last):
  File "C:\VersionControl\PythonScripts\Source\src\lib\Python27\ArcGIS10.1\lib\site-packages\sphinx\ext\autodoc.py", line 335, in import_object
    __import__(self.modname)
  File "C:\VersionControl\PythonScripts\Source\src\gis\scripts\script_export_pdf.py", line 76, in <module>
    mxd.ExportToPDF(in_mxds, out_folder, overwrite, current)
  File "C:\VersionControl\PythonScripts\Source\src\gis\mapping\mxd.py", line 315, in ExportToPDF
    _ExportToPDF(arcpy.mapping.MapDocument(m), out_folder, overwrite)
  File "C:\Program Files (x86)\ArcGIS\Desktop10.1\arcpy\arcpy\arcobjects\mixins.py", line 609, in __init__
    assert (os.path.isfile(mxd) or (mxd.lower() == "current")), gp.getIDMessage(89004, "Invalid MXD filename")
AssertionError: Invalid MXD filename.

我通过在测试开始时设置一个变量来解决单元测试中的这个问题，脚本会检查该变量并在参数中设置测试值，我想知道 sphinx 是否有类似的解决方法？

【问题讨论】：

标签： python python-sphinx arcpy

【解决方案1】：

我想出的解决方案虽然可能远非理想，但只是简单地检查

if 'sphinx' in sys.modules:
    in_mxds = [r"C:/test.mxd"]
else:
    in_mxds = arcpy.GetParameterAsText(1)

这将确保脚本不会尝试从 GUI 获取在生成 sphinx 文档时未设置的参数。

【讨论】：

对于大多数项目来说都是一个很好的 hack！不幸的是，如果您正在记录 sphinx 扩展，它将无法工作：/

【解决方案2】：

我做这样的事情。在我的conf.py 中，我向builtins 模块添加了一个新变量，例如：

# anywhere in conf.py before any of your modules are imported
import builtins
builtins.__sphinx_build__ = True

然后在我的模块代码中，我可以编写如下检查：

try:
    from some_dependency import SomeClass
except ImportError:
    try:
        if __sphinx_build__:
            class SomeClass:
                """Mock the class"""
    except NameError:
        raise ImportError('some_dependency')

【讨论】：

【解决方案3】：

如果您的项目正在导入 sphinx（在我的情况下是 sphinx 扩展），以下内容也可能适合您

import os
import sys
if os.path.basename(sys.argv[0]) == "sphinx-build":
    # code for when sphinx is running
else:
    # code for regular application

我不确定这是否适用于 Windows，或者是否应该类似于

if os.path.basename(sys.argv[0]) in ["sphinx-build", "sphinx-build.exe"]:

【讨论】：

【解决方案4】：

自 Sphinx 1.3 以来，此问题有一个简单的解决方案。只需添加

autodoc_mock_imports = ['arcpy']

到你的 conf.py。这可以在构建时不满足某些外部依赖项并破坏构建过程时使用。见Sphinx: how to exclude imports in automodule?。

不幸的是，Esri 的 arcpy 文档非常差，而且大多忽略了 Python 标准。

【讨论】：