Autodoc: Allow mocked module decorators to pass-through functions unchanged

[mleinart]

Summary

Autodoc's autodoc_mock_imports feature is useful for both ignoring imports and any module-level statements or class definitions that use those imports.

One category of imported objects that are most commonly used at the module level are decorators. I propose support for mocking imports that are used as decorators in autodoc'd modules.

Current Behavior

When a mocked import in an autodoc'd class is a decorator used on functions or methods in that module, the function, class, or method it decorates will be replaced with a _MockModule instance and the original definition discarded. This makes it impossible to autodoc anything decorated in projects where the decorator is from a mocked import.

Proposed Behavior

_MockModule should do a simple inspection on call()s to guess whether the mock instance is being called as a decorator and if so, pass through the original object unchanged.

Example Use Case

The Fabric project defines execution tasks in Python by decorating module-level functions with a decorator. If 'fabric' (and its submodules) is added to the list of mocked modules in conf.py, it becomes impossible to use autodoc to generate documentation on this config.

Note: This would also make Fabric's Sphinx helper unwrap_tasks() unnecessary, simplifying conf.py for Fabric users

[tk0miya]

+1
Could you add any testcases for this?

[mleinart]

@tk0miya added a couple tests and verified failure without this change, success with it.

Let me know if this doesn't turn out to be the best place to put these tests. I used test_generate since that's what calls import_object() where the mocking takes place and it's got pretty appropriate assertion helpers for these tests

[tk0miya]

Merged.
Thank you for contribution!