I am trying to use Sphinx to document a Python file, which is being used to implement a GIMP Plugin. The problem is, when I run;
make html
I get the following messages - which as can be seen below, yield an error;
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v2.2.0
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] code
WARNING: autodoc: failed to import module 'Plugin_ImageOverlay'; the following exception was raised:
Traceback (most recent call last):
File "/home/craig/.local/lib/python3.5/site-packages/sphinx/ext/autodoc/importer.py", line 32, in import_module
return importlib.import_module(modname)
File "/usr/lib/python3.5/importlib/__init__.py", line 126, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
File "<frozen importlib._bootstrap>", line 986, in _gcd_import
File "<frozen importlib._bootstrap>", line 969, in _find_and_load
File "<frozen importlib._bootstrap>", line 958, in _find_and_load_unlocked
File "<frozen importlib._bootstrap>", line 673, in _load_unlocked
File "<frozen importlib._bootstrap_external>", line 665, in exec_module
File "<frozen importlib._bootstrap>", line 222, in _call_with_frames_removed
File "/home/craig/.gimp-2.8/plug-ins/ImageOverlay/Plugin_ImageOverlay.py", line 73, in
<module>
from gimpfu import register, main, pdb, gimp, PF_IMAGE, PF_DRAWABLE, PF_INT,
PF_STRING, PF_FILE, PF_BOOL, INTERPOLATION_NONE, INTERPOLATION_LINEAR,
INTERPOLATION_CUBIC, INTERPOLATION_LANCZOS, PF_RADIO
File "/usr/lib/gimp/2.0/python/gimpfu.py", line 235
raise error, "parameter name contains illegal characters"
^
SyntaxError: invalid syntax
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindexdone
writing additional pages... search/home/craig/.local/lib/python3.5/site-
packages/sphinx_rtd_theme/search.html:20: RemovedInSphinx30Warning: To modify script_files
in the theme is deprecated. Please insert a <script> tag directly in your theme instead.
{{ super() }}
done
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.
The HTML pages are in _build/html.
Build finished. The HTML pages are in _build/html.
In case it is not obvious from the above output, the error message reads;
File "/usr/lib/gimp/2.0/python/gimpfu.py", line 235
raise error, "parameter name contains tllegal characters"
^
SyntaxError: invalid syntax
I don't know a great deal about Python or Sphinx, but does this error have something to do with the differences in syntax between Python versions 2 and 3? My Plugin can be loaded and executed without any problems by GIMP - so why does Sphinx seem to choke on it?
Is there some easy workaround for this that I'm not aware of, such as a key-value pair that can be placed in Sphinx's conf.py file?
Thanks in advance for any assistance.
You're using version 2.2.0 of Sphinx, and Sphinx dropped support for Python 2 since 2.0.x
The raise error, e style in gimpfu.py is not supported in Python 3.x. (you're expected to use raise error(e))
You could try using an older version of Sphinx that supports Python 2, or hacking gimp to use a Python 3 compatible syntax, or asking the gimp people to fix it...