How can I tag a docstring for conditional inclusion in Sphinx?

Question

I have extensive docstrings in my Python package classes and methods that are brought into Sphinx using the autodoc directive to generate the project docs.

Some of the external (not starting with underscore) methods are API methods that should appear in the user documentation. Others are external because they need to be called from another module, but make up an internal API. These should not appear in the user documentation.

So far, I have manually distinguished user API methods from internal API methods using the :members: parameter. This turns out to be error prone as I add new methods and I would like to indicate right in the docstring whether the method should appear in user API docs.

Is there a way I can "tag" the docstring or something like that to appear directly in the source code to indicate it should appear in user API docs?

score 3 · Answer 1 · edited May 23 '17 at 11:51

Looks like you want to exclude members from the autodoc?

.. automodule:: yourmodule
   :inherited-members:        # include inherited functions
   :special-members:          # include __functions__
   :private-members:          # include _functions and __functions
   :members:                  # include all other documented functions
   :undoc-members:            # include even undocumented functions
   :exclude-members: f_1, f_2 # exclude certain members

To work out the condional documentation more programmatically, you'd edit the conf.py file and override the slot autodoc-skip-member like explained here.

def skip(app, what, name, obj, skip, options):
    return name in ["exclude1", "exclude2", "exclude3"]

def setup(app):
    app.connect("autodoc-skip-member", skip)

How can I tag a docstring for conditional inclusion in Sphinx?

1 Answers1