How to document only a subset of functions in Sphinx?

user_4474930 0
Viewed 384

Using Sphinx, I need to generate two sets of documentation for my Python app:

  1. Contains all my modules/functions
  2. Contains only a subset of functions from my modules

I want to use a "tag" in the function docstrings that would indicate whether or not to include the function in the 2nd set of documents.

With .. only, I'm able to control which part of the docstring gets included depending on -t <tagname> that I provide to sphinx-build. But I'm not able to find any way of filtering out a set of functions to be included in the scope of the documentation based on docstring entries of these functions.

python-sphinx python
1 Answers

As it usually happens - after posting question you come up with the answer. Managed to achieve this using https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#skipping-members and putting following code to conf.py

def include_only_tagged(app, what, name, obj, skip, options):
    inclusion_tag_format = ".. only:: {}" #can be any pattern here, choose what works for you
    for tag in app.tags.tags:
        if obj.__doc__ is not None and inclusion_tag_format.format(tag) in obj.__doc__:
            return False
    return True
    
def setup(app):
    if(len(app.tags.tags)>0):
        app.connect('autodoc-skip-member', include_only_tagged)

So if I use something like ".. only:: subset" as part of my docstring for any function - that says that whenever I run sphinx-build -t subset only this function(s) will be kept in scope of generated documentation.

user_44749300
Related