autosummary broken on various packages

[larsoner]

We use RST code like the following in several places:

Visualization
=============

:py:mod:`mne.viz`:

.. automodule:: mne.viz
 :no-members:
 :no-inherited-members:

.. currentmodule:: mne.viz

Classes:

.. autosummary::
   :toctree: generated/
   :template: class.rst

   ClickableImage

Functions:

.. autosummary::
   :toctree: generated/
   :template: function.rst

   circular_layout
   mne_analyze_colormap

This used to produce nice docs, but on master and the version currently distributed with Anaconda, doc building completes but the areas above are now blank. I have bisected the problem to this commit:

21b8384

commit 21b838454f4bb5b6a246b85cb2f521deb7552505
Author: Luc Saffre <[email protected]>
Date:   Sat Jan 3 20:32:44 2015 +0200

    autodoc: use sourcename also for content generated by autodoc itself

    Fixes #1061
    Fixes #1656

Any idea what the problem could be?

[larsoner]

I've isolated the problem to the addition of these two lines in sphinx/ext/autosummary/__init__.py:

            if not documenter.check_module():
                continue

Commenting out those lines fixes doc building for us. Now I'm going to investigate why the check_module is failing...

[larsoner]

Oh, it's because a bunch of our classes and functions aren't defined in the specific module, so this check fails:

    def check_module(self):
        """Check if *self.object* is really defined in the module given by
        *self.modname*.
        """
        if self.options.imported_members:
            return True

        modname = self.get_attr(self.object, '__module__', None)
        if modname and modname != self.modname:
            return False
        return True

So it looks like if we can set options.imported_members = True, we should be good to go. Now to figure out how to set the imported-members option.

[larsoner]

Ahh wait, I think this is actually a bug. Here is the documentation:

In an automodule directive with the members option set, only module members whose __module__ attribute is equal to the module name as given to automodule will be documented. This is to prevent documentation of imported classes or functions. Set the imported-members option if you want to prevent this behavior and document all available members. Note that attributes from imported modules will not be documented, because attribute documentation is discovered by parsing the source file of the current module.

But in our code, the members option is not set -- in fact no-members is set, because we want to manually specify our names. So I think the check above should only occur if members is set. I'll see if I can figure out how to query that option.

[jschueller]

is it a duplicate of #1822 ?

[larsoner]

Yep!