CODEWITHSUNDEEP
pythonpython-sphinxautodoc
Colton Leekly-Winslow
Colton Leekly-Winslow

Reputation: 853

Sphinx Autodoc skip member from docstring

I am documenting a class with Sphinx and simple want to skip one of the classes members:

class StatusUpdateAdapter(logging.LoggerAdapter):
    """
    """
    def __init__(self, status_update_func, logger, extra={}):
        """
        """
        pass

    def log(self, *args, **kwargs):
        pass

How can I cause sphinx NOT to document the log member? I would like to do this in the StatusUpdateAdapter or log docstring's if possible.

Upvotes: 32

Views: 21237

Answers (6)

Kevin
Kevin

Reputation: 30151

There doesn't appear to be any easy way to do this.

As a workaround, you can try something like this in your RST file:

.. autoclass:: StatusUpdateAdapter
   :members: methodA, methodB

But that requires listing out all the methods you do want to document by hand, which could be quite laborious. It also probably doesn't interact well with :inherited-members:, if you're using that.

Another option is to put a docstring on every method you want documented, but no docstring on the log() method, then (if necessary) use :no-undoc-members:. This is obviously no good if you plan on documenting your internal interfaces or not documenting your public interfaces.

Finally, Autodoc skips anything whose name begins with an underscore unless configured otherwise (:private-members:), so if you use an underscore-prefixed name, the method will not appear. Underscore-prefixing indicates a private interface under PEP 8, which may or may not match up with your intentions. This could also create backwards compatibility headaches in an established codebase.

Upvotes: 8

leszek.hanusz
leszek.hanusz

Reputation: 5317

You can use :meta private: so that Sphinx considers the method as private and it will be hidden if you configure Sphinx to hide private methods.

Documented at https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#directives section "Options and advanced usage":

autodoc considers a member private if its docstring contains :meta private: in its Info field lists. For example:

def my_function(my_arg, my_other_arg):
    """blah blah blah

    :meta private:
    """

And :private-members: needs to be turned off, otherwise the field will still show.

Upvotes: 13

sarusso
sarusso

Reputation: 713

Had a similar issue, and given that (even) as of today there seems to be no such feature, I found a workaround-ish option that worked for me: creating a custom autodoc-skip-member() function in the conf.py.

This allows to define when to skip members based on a few inputs including the type of the object, the name of the object and the object itself.

See this question for more details: Connect Sphinx autodoc-skip-member to my function, and in particular this answer (returning None allows to let Sphinx use the default behaviour for members not explicitly excluded).

Upvotes: 0

Petar Donchev
Petar Donchev

Reputation: 399

Years too late, but an ugly workaround is to add an empty docstring to the public method that you want to skip. Like that:

def log(self, *args, **kwargs):
    ""
    pass

Upvotes: -3

Mr. Heuristic
Mr. Heuristic

Reputation: 114

I'm not sure how to do that with a docstring, but you can declare the function/method 'protected' with a prepended underscore. Sphinx will not pull that function/method in.

def _log(self, *args, **kwargs):
     pass

Upvotes: 5

OdinX
OdinX

Reputation: 4201

You can now (as of version 0.6) use :exclude-members: to exclude specific members from the documentation:

The directives supporting member documentation also have a exclude-members option that can be used to exclude single member names from documentation, if all members are to be documented.

New in version 0.6.

Source: http://www.sphinx-doc.org/en/stable/ext/autodoc.html

In your specific case, you would add :exclude-members: log into your .rst file.

Upvotes: 23

Related Questions