How to customize Python domain in Sphinx?

Question

I’d like to customize the Sphinx Python domain to recognize a custom field within a docstring for a method and generate custom HTML for it.

For example, let’s say I want to add a category for each method in a module. I want to be able to write a doc string like this:

def func():
    “””
    Does something

    :category: A/B/C
    “””
    …

and then have custom HTML display on the generated autodoc.

Is this possible?

Answer 1

Yes, it is, but it will require code (a custom extension) and might not be easy.

There might be a simpler way, but by subclassing PyClassLike, probably changing the values of doc_field_types and registering this with app.add_directive_to_domain("py", "class", YourClass, override=True) in a setup(app) fonction in your conf.py, you might get what you want.