search

repoze / repoze.sphinx.autointerface

Auto-generate Sphinx API docs from Zope interfaces
http://pypi.python.org/pypi/repoze.sphinx.autointerface
Other
8 stars 7 forks source link

:members: is not really respected? #7

Closed jamadden closed 8 years ago

jamadden commented 8 years ago

At least not with modern Sphinx (1.4).

This stems from a conversation @jimfulton and I were having over in zodbdocs. When I tried to test :members: in a local RelStorage checkout, it appeared to be completely ignored and everything in the interface was documented.

I could have missed something and there's no test cases here to check on so I'll have to try a smaller example at some point.

Jim's version of the interface documenter class is much simpler, maybe because it supports newer Sphinx versions only?

jimfulton commented 8 years ago

First, "mine" is just a fork with small fixes. :) Second, it's probably simpler because it subclasses bits from autodoc, especially autoclass. (It looks like autodoc made some specific accommodations for it.)

Of course, simpler because lines of code, but maybe not so much because inheritance. :)

jamadden commented 8 years ago

rezpoze.sphix.autointerface.InterfaceDocumenter subclasses the same sphinx.ext.autodoc.ClassDocumenter as your fork does.

jamadden commented 8 years ago

It turns out that autointerface respects :members: just fine, as long as you don't have them turned on by default. The same thing goes for autoclass.

If you have members enabled by default in conf.py:

autodoc_default_flags = ['members']

then the AutoDirective will override whatever you put for :members: in any particular directive with None---which turns into ALL.

The solution is to put :no-members:, and then :members: my,list,of,members, e.g.:

.. autointerface:: relstorage.adapters.interfaces.IRelStorageAdapter
     :no-members:
     :members: connmanager

In the process of figuring this out, I have the start of a test suite for this package, so I'll open a PR for that.