Sphinx Public API documentation

python, python-sphinx

Solution

I'm answering my own question... After some more had searching I found this:

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#skipping-members

Basically you can define a function in your `conf.py` file can look at each member and skip all that don't have the right decorator.

Here is a little example at the end of my `conf.py` file (this is the config file for sphinx):

def my_doc_skip(app, what, name, obj, skip, options):
    if what != "method":
        return True

    # if obj is decorated with @api
    #     return True
    # return False

def setup(app):
    app.connect('autodoc-process-docstring', my_process_docstring)
    app.connect('autodoc-skip-member', my_doc_skip)

You can also process the docstring with a function.

Problem

I have a large number of python file and I would like to generate public API documentation for my project. All the functions that are part of the api I have decorated with a decorator. for example: ``` @api def post_comment(comment)" """ Posts a coment """ pass ``` There are other public methods in the same classes. The API is spread among several files each file defining classes with methods and some methods have this @api decorator. How can I tell Sphinx to generate docs just for the public API?

Original source