Geek asks and answers

Ask sphinx to replace docstring text

I am documenting code in Sphinx that resembles this:

class ParentClass(object):

    def __init__(self):
        pass

    def generic_fun(self):
        """Call this function using /run/ParentClass/generic_fun()"""
        do_stuff()

class ChildClass(ParentClass):

    def specific_fun(self):
        """Call this function using /run/ChildClass/specific_fun()"""
        do_other_stuff()

I added documentation :inherited-membersto ChildClass, so I have instructions there, for example: "Call this function with / run / ParentClass / generic _fun ()".

Is there a way I can put something in docstrings so that sphinx will replace the actual class that it is documenting?

I would like the code to look like class ParentClass (object):

    def __init__(self):
        pass

    def generic_fun(self):
        """Call this function using /run/<class_name>/generic_fun()"""
        do_stuff()

So, in the ChildClass section, the Sphinx documentation will read ... using / run / ChildClass / generic_fun () ... and the ParentClass section will read ... using / run / ParentClass / generic_fun () ...

Ideally, I would like to have the documentation on the same page, so the replacement string will be different for different sections.

+5
1

, - .

autodoc. conf.py:

def get_class_name(full_module_name):
    """
    Pull out the class name from the full_module_name
    """
    #split the full_module_name by "."'s
    return full_module_name.split('.')[-1]

def process_docstring(app, what, name, obj, options, lines):
    classname = get_class_name(name)

    # loop through each line in the docstring and replace |class| with
    # the classname
    for i in xrange(len(lines)):
        lines[i] = lines[i].replace('|class|', classname)

def setup(app):
    app.connect('autodoc-process-docstring', process_docstring)

| . , ( | | |):

.. |class| replace:: `|class|`
+7

More articles:


All Articles