Duplicate member descriptions for ABC-derived classes are created.

[mjstahlberg]

It seems like the opposite effect of #52 is happening as of version 0.9: Class members for ABC-derived classes are displayed twice. Please refer to https://gitlab.com/picos-api/picos/issues/117 for a full issue description (I was about to post it here initially, but GitHub wouldn't let me upload the image).

[astrofrog]

@Viech - can you try and include (if you haven't already) the following in your conf.py file?

numpydoc_show_class_members = False

[mjstahlberg]

Hello @astrofrog, I already tried that after I found it in the documentation, but it makes no difference. I also don't recall using anything called numpydoc in my setup. I rather suspect the issue might be related to #53.

[astrofrog]

It looks like this is an issue that happens only with Sphinx 1.8, not e.g. with Sphinx 1.6. I'll try investigating.

[astrofrog]

There's something weird going on with Sphinx, even if I don't use automodapi and just do:

KullbackLeiblerConstraint
=========================

.. currentmodule:: picos.constraints

.. autoclass:: KullbackLeiblerConstraint
   :show-inheritance:

   .. rubric:: Attributes Summary

   .. autosummary::

      ~KullbackLeiblerConstraint.dual

   .. rubric:: Attributes Documentation

   .. autoattribute:: dual

I get the extra three entries at the bottom:

I think this is a Sphinx bug rather than a sphinx-automodapi issue.

[astrofrog]

@Viech - this appears to be due to the:

    'undoc-members': None,

option you have in your conf.py. Removing this result in the duplicate entries going away. I'm not sure there's anything we can fix in sphinx-automodapi though, as the example above shows it happens even without sphinx-automodapi.

[mjstahlberg]

@astrofrog you are correct, removing that option removes the duplicate entries. So autoclass documents undocumented members with that option while it should not ever document any members?

This is not an ideal solution for me as I'm using a mix of automodapi and regular sphinx and I do want undocumented public members to show in the "regular" part of the documentation, but it helps me to work around the issue.

[astrofrog]

@Viech - just to clarify, do you mean you don't want undocumented methods/attributes to show up at all in the API docs?

[mjstahlberg]

@astrofrog no, i do want them to show up because right now there are a couple of self-explaining undocumented public methods that should be part of the documentation (e.g. picos.tools.is_integer which is generated by automodule).

[astrofrog]

@Viech - ok I see. If you just use sphinx-automodapi it should actually show undocumented methods by default, so that might be sufficient? If you would like to see additional options in automodapi (apart from those in https://sphinx-automodapi.readthedocs.io/en/latest/automodapi.html) then let me know what would be useful to have.

[mjstahlberg]

@astrofrog, what I really want is a consistent documentation for a project/package picos that contains both modules (e.g. the single file picos/tools.py) and subpackages (e.g. the directory picos/constraints that contains the module meta_kldiv.py from above and many others). I'll play around with using automodapi everywhere but I feel like that

1. using automodapi on the full picos package would leave me with too little control (e.g. I couldn't explain the different modules and subpackages like I do here) and
2. using automodapi also on modules (instead of automodule) gives weird output: First the module contents are listed in detail, and then there is the functions/classes/diagram overview, with the links leading to seperate html pages that contain the detail descriptions again. This is very different from the simple page produced for every module in a package if automodapi is used on that package.

I think I could get it all right and consistent if I had a way to control the template that automodapi uses to create both the package .rst and each individual module .rst. I could then just leave :undoc-members: enabled in my global configuration, and make the module template match the module .rst files that I write manually.

EDIT: With respect to (1), I found that automodapi does not recurse into modules and subpackages, so just using .. automodapi:: picos does not give me a full documentation but documents only the members that I import into the picos namespace (in picos/__init__.py).

[mjstahlberg]

I spent the day finding an almost consistent format for the PICOS documentation. For me this issue is resolved. Note that others might still be affected when they enable undoc-members globally.

[mjstahlberg]

Actually the issue is still there, however it affects documented attributes now. I think the problem is that :autoclass: respects the autodoc_default_options global option, where I still have 'members': None. I can easily remove that and supply members manually with every automodule, but if you find a fix that works regardless of the global configuration that would probably be ideal for your users.