FIX: Only check if members is True

[larsoner]

Closes #1891.
Closes #1822.

check_module should only be called if members is currently activated, otherwise formely working use cases like those in #1891 are broken. This is also consistent with the docs:

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.

Ready for review/merge from my end.

[jschueller]

hello i proposed a fix in #1828 for these two lines, maybe yours is a cleaner fix ?

[larsoner]

@jschueller can you confirm that this fixes the bug on your build? That might help the review process proceed.

[jschueller]

it does fix my OpenTURNS build (#1822)

[jschueller]

@shimizukawa @lsaffre is it still ok regarding #1061 ?

[lsaffre]

Yes, it is okay. Sorry for my slow reply (I am still unexperienced with
git, and it took me some effort to rediscover what it was about:
http://luc.lino-framework.org/blog/2015/0614.html)

On 13/06/15 11:28, jschueller wrote:

@shimizukawa https://github.com/shimizukawa @lsaffre
https://github.com/lsaffre is it still ok regarding #1061
#1061 ?

—
Reply to this email directly or view it on GitHub
#1892 (comment).

[jschueller]

good, thanks @lsaffre !
@shimizukawa @birkenfeld could you please review this one ? this regression is known to affect at least these python packages:

• Sphinx 1.3.1 breaks API docs scikit-learn/scikit-learn#4737
• DOC: API docs broken with sphinx 1.3.x pandas-dev/pandas#10316
• readthedocs dask.bag.api documentation is not autogenerating dask/dask#284
• trac.openturns.org/ticket/785

[larsoner]

It also fixes problems I've had with at least three of my repos (mne-python, pyeparse, expyfun, ...).

[jschueller]

hi, @shimizukawa, is this still ok for you ?

[shimizukawa]

LGTM.

Sorry for late reply.
My understanding is:

• The change for autosummary document imported functions #1061 deny all imported members by default.

• autosummary doesn't have imported-members option to allow documenting imported members.

• Many of users are using autosummary like:

  .. autosummary::
     :toctree: _generated
  
     package.module.ImportedClass
  

• The document of :members: option for autodoc mentioned that the option avoid imported members, so if you want to allow such members, you can use :imported-members:. The change of this PR doesn't violate the documented behavior.

• If you use :members: option for autodoc_default_flags and you want to allow imported members, you should specify :imported-members: option for autodoc_default_flags. However it has side-effect; all imported members of all modules will be documented.

Todos:

• Still we need a option to allow documenting imported members in any of the ways;
  • :imported-members: option for autosummary directive
  • a conf.py option to disable documenter.check_module() in autosummary directive.

[shimizukawa]

Merged!
Thanks for your cooperation!

[jschueller]

@shimizukawa, thank you
can we expect a bugfix release this summer ?

[birkenfeld]

There will be a sprint at EuroPython. At the end there will definitely be another release.

[amueller]

I tried autodoc_default_flags = ['members', 'inherited-members', 'imported-members'] but that didn't include any additional classes. I also just did autodoc_default_flags = ['imported-members'] with the same result. Did I misunderstand your comment above @shimizukawa? (version 1.3.1)