Sphinx apidoc configuration

First, see sphinx configuration for configuring sphinx.

Mocking Libraries

Some code will not be available when rendering sphinx. This might be only available within a custom interpreter (ex: vim, maya), or initializing classes might run code that connects to a database, or something else you might not want to depend on to produce docs.

It is considered a best practice to mock out these modules. If using the autodoc directive, it will even do this for you.

# BEST:
autodoc_mock_imports = ['shiboken', 'shiboken2', 'pymel', 'maya', 'sqlalchemy']

# MANUAL:
for module in ('shiboken', 'shiboken2', ...):
    sys.modules[module] = mock.Mock()

This will solve most problems within sphinx-build, but if you run your own code to produce apidocs (for example), you will also have to perform mocks within their run environment so that they work. For mocking maya, I found I needed to recreate the entire maya module.

Mocking classes was not sufficient in the following cases:

• classmethods/staticmethods
• class attributes
• mock instances cannot be used as a type in isinstance

For this reason, I wrote a module to map-out/fake the entire maya package. See tma.lib.sphinxdoc.fakepkg.