provide option to include private and special members

Chad Dombrova avatarChad Dombrova created an issue

it's pretty standard practice in API documentation to include special methods such as:

__add__, __mul__, __div__

because they are essential to conveying the purpose and usage of the class. additional options should be added along the lines of "undoc-members", for including special methods:

__foo__

and private methods:

_foo, __foo, _foo_

it's important to have individual control over these since it is often the case that private members should be skipped while special members should be documented.

.. autoclass:: Foo
  :members:
  :private-members:
  :special-members:

NOTE: i am aware that "autodoc-skip-member" event can be used for this purpose, but 99% of us are not willing to write custom modules and callbacks to accomplish something as simple and essential as including private members -- it should just work. to my knowledge, the sphinx docs do not even provide examples of how one would go about hooking up an event callback. it is unrealistic to expect the average user to delve into this magic to accomplish something so fundamental.

Comments (15)

  1. Anonymous

    +1. I am surprised there is not more demand for this--I've been trying to find autodoc-skip-member examples myself with no success. Sphinx can document the init method with the autoclass_content setting, but that's not ideal and frankly seems like a hack; there are many other special (non-private) methods that the API user will want to know about, like getitem, getattr, gt, lt and so on in addition to the ones chadrik mentioned above. It would be great if I could just put something like "include_private=True" in my conf.py to include these in the documentation. Right now my only alternative seems to be to include explicit autofunction directives for all the "private" methods I want to include.

  2. Éric Araujo

    Not sure whether this is a dupe of #520. Copying my comment: IMO magic methods don’t have to be documented for a specific class since they’re documented once in the Python docs.

  3. Chad Dombrova

    yes, but magic members can be used to do different things on different classes. certainly the python docs for these methods are not universally applicable. for example, on a vector class pow might do cross product. and for magic methods that take an input, like mul, div, etc, it's very necessary to document what type of object it works with on a particular class. the docs might also provide examples of how to use the special methods in the context of the class being documented. especially for classes that make heavy use of the numeric magic methods, not documenting all of this is a huge omission.

    also, this feature request covers private methods as well, which are sometimes necessary to document. i'm not suggesting these two features should be on by default, but they should exist.

  4. Max Cantor

    +1!

    This is vital for internal documentation.

    I'm trying to use Sphinx to generate internal documentation for a huge codebase.

    I'm not just documenting the public API.

    It is not for public consumption; it's meant to be read and used by our internal developers, particularly with new hires or when people switch teams and projects.

    autodoc-skip-member doesn't work

    Right now, you can't even use autodoc-skip-member, because the event isn't fired by a lone :members: directive: you must explicitly list members, which kind of defeats the purpose.

  5. Kevin Horn

    Max:

    I certainly had no intention of changing the component for this issue. Either I did it accidentally or bitbucket's form did it for me.

    In any case, thanks for fixing it.

  6. Max Cantor

    Hello all. I have attached a patch which enables this functionality. This didn't seem like a big enough change to warrant forking the entire repository, but I couldn't figure out the right way to submit a plain old patch file. So... here it is! I also "updated" the tests, though only cursorily; the existing tests are a little hairy, and did not seem to cover the member skipping logic.

    I am presumptuously assigning this issue to Mr. Brandl; not sure who is actually supposed to vet patches. Thanks!

    kevin: No prob!

    Also, it seems I spoke too soon when I blaringly declared "autodoc-skip-member doesn't work" before; it works fine! I erroneously thought that the sphinx-build script counted "conf.py" as a dependency. I interpreted the lack of difference in my resulting docs as an indication that autodoc-skip-member wasn't working as expected, when in fact, it simply wasn't being emitted because I hadn't deleted my _build directory.

  7. Log in to comment
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.