Check if Sphinx doc called the script

user_2796924 0
Viewed 1488

I am currently trying to generate sphinx documentation for scripts which use the ArcGIS arcpy library.

I am running into an issue when sphinx tries to run the scripts while generating the documentation, as arcpy scripts take input parameters from the arcgis gui. Since sphinx is calling the scripts without the gui, these parameters are empty and are causing Tracebacks such as:

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.

I get around this issue in unittests by setting a variable when the test begins which the script checks for and sets test values in the parameters, I am wondering if there is a similar workaround with sphinx?

arcpy python-sphinx python
4 Answers

I do something like this. In my conf.py I add a new variable to the builtins module like:

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

Then in my module code I can write a check like:

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

Since Sphinx 1.3 there is a simple solution for this issue. Just add

autodoc_mock_imports = ['arcpy']

to your conf.py. This can be used when some external dependencies are not met at build time and break the building process. See Sphinx: how to exclude imports in automodule?.

It's unfortunate that Esri has very poor arcpy documentation and mostly ignores Python standards.

user_49267610
Related