The autodoc_mock_imports option requires to explicitly declare *every*
external module and sub-module that are imported by the documented code.
This is not practical as the list can become very large and must be
maintained as the code changes.
Also, the mocking is minimal which causes errors when compiling the
docs. For example, if you declare:
autodoc_mock_imports = ['django.template']
And try to document a module:
.. automodule:: my.lib.util
Which contains this code:
from django.template import Library
register = Library()
The following error occurs:
File ".../my/lib/util.py" line 2
register = Library()
TypeError: 'object' object is not callable
Other similar errors can occur such as "TypeError: 'object' object has
no len".
To address these limitations, only require to declare the top-level
module that should be mocked:
autodoc_mock_imports = ['django']
Will mock "django" but also any sub-module: "django.template",
"django.contrib", etc.
Also, make the mocked modules yield more complete dummy objects to avoid
these TypeError problems.
Behind the scenes, it uses the python import hooks mechanism specified
in PEP 302.
Signed-off-by: Robin Jarry <robin@jarry.cc>
The method new is an alternative to __init__, but autoclass does not
respect __new__. This commit enhances the directive autoclass:: to try
__new__ method's docstring, if __init__ method's docstring is missing or
empty.
The commit also adds tests and updates the documentation.
The :novalue: option is now called :annotation: and has an additional feature:
When given with an argument, you can specify what the annotation
of the object will be.
#482: When doing a non-exact search, match only the given type of object.
#481: Apply non-exact search for Python reference targets with ``.name`` for modules too.
configurable either with the config value ``autodoc_member_order`` or a ``member-order`` option per directive.
Also fix a bug that documented module-level functions as attributes.
