Sphinx extensions in 3rd-party imports should not cause errors

[shimizukawa]

My Sphinx builds on Jenkins have started failing since I've upgraded to SQLAlchemy 0.9.6. The build log shows the following error:

#!python
Fatal error: Failed to build documentation.
/.../virtualenvs/ed16c39d/lib/python2.7/site-packages/foo/models.py:docstring of foo.models.case:12: ERROR: Unknown interpreted text role "paramref".

Where models.py includes:

#!python
from sqlalchemy import case

The case import causes Sphinx to load SQLAlchemy code which uses the :paramref: directives from this Sphinx Extension.

My project does not use :paramref: directives, but Sphinx produces an error because my project imports 3rd-party code which does use :paramref: directives. I could work aroudn this issue by adding the "paramlinks" extension to my project, but it seems less than ideal to have to include Sphinx extensions because of choices made in external projects/dependencies.

The Keystone (OpenStack) project encountered a similar issue and resolved it by importing the sqlalchemy package instead of the culprit functions themselves:

For example:

#!python
- from sqlalchemy.sql import select
+ import sqlalchemy
- duplicated_rows_select = select(...)
+ duplicated_rows_select = sqlalchemy.sql.select(...)

It'd be great if Sphinx could avoid this type of issue itself, or if there was an option to ignore errors of this sort.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1530
• Originally reported by: Ben Beanfield
• Originally created at: 2014-08-06T23:18:01.063

[steenzout]

any news on this?

[shimizukawa]

@steenzout Please try autodoc_mock_imports feature that is provided from Sphinx-1.3b1.
http://sphinx-doc.org/latest/ext/autodoc.html#confval-autodoc_mock_imports

[kyouko-taiga]

Hi guys,

I am experiencing the same issue with some project using SQLAlchemy. As suggested by @shimizukawa, I tried the autodoc_mock_imports feature. Unfortunately this makes things even worse, as it makes sphinx unable to load SQLAlchemy and thus fail to load my modules at all.

Correct me if I am wrong, but my understanding of autodoc_mock_imports is that the feature has been added to prevent sphinx to fail on modules that can't be imported at build time (as hinted in the documentation).

[tk0miya]

I think it's difficult to prevent such errors from sphinx core. Only we can do is stopping to read docstring from super classes.