__repr__(), util.object_description() and ext.autodoc.add_directive_header()

Calling autodoc with undoc-members invokes eventually sphinx.ext.autodoc.add_directive_header() which calls sphinx.util.object_description(), which calls repr(object), which in turn calls __repr__() on the parameter.

Django.db.models.query.__repr__() tries to connect to the underlying database and throws django.db.utils.OperationalError "Connection refused" when it has bad luck. In such cases the output of __repr__() shall not be used, but the "Connection refused" shall be shown to the user. However object_description() converts the exception to ValueError and add_directive_header() discards it.

On another occasion sphinx.ext.autodoc.add_directive_header() calls again sphinx.util.object_description() but with a dict-instance as parameter. Then return "{%s}" % ",".join(items) in object_description() calls __repr__() (or __str__() - it does not matter) and objects_description() throws an exception that is not ValueError, so that the backtrace is shown to the user and the user can take actions.

Finally when sphinx-buld -v -v is run it calls super().format() which calls lib/python3.x/log/__init__.LogRecord.get_message(), which calls again __repr__() and in this case the connection error is emitted while the documentation is generated. It is unfeasible to call -v -v to track for such errors, as there is a lot of cluttered output, and according to my understanding sphinx is supposed to emit warnings without being called with -v.

Summa summarum Autodoc shall inform the user, when during documentation generation __repr__() is called and fails in a manner, that user action is required to generate the full documentation correctly. Currently this is only sometimes the case.

I use Sphinx 1.7.