Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Have Sphinx 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 the :inherited-members to the ChildClass documentation, so I have statements in there like "Call this function using /run/ParentClass/generic_fun()".

Is there a way I can put something in the docstrings like <class_name> that Sphinx will replace with the actual class that it's documenting?

I would like to have the code 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 would read "(...) using /run/ChildClass/generic_fun()(...)" and the ParentClass section would read "(...) using /run/ParentClass/generic_fun()(...)"?

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

like image 897
Charles L. Avatar asked Jul 28 '12 02:07

Charles L.


People also ask

How do you format a Sphinx docstring?

The Sphinx docstring formatA pair of :param: and :type: directive options must be used for each parameter we wish to document. The :raises: option is used to describe any errors that are raised by the code, while the :return: and :rtype: options are used to describe any values returned by our code.

What does Sphinx Autodoc do?

autodoc imports the modules to be documented. If any modules have side effects on import, these will be executed by autodoc when sphinx-build is run. If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition.

Can you format a docstring Python?

Python docstrings can be written following several formats as the other posts showed. However the default Sphinx docstring format was not mentioned and is based on reStructuredText (reST). You can get some information about the main formats in this blog post.

What is RST Sphinx?

RST stands for ReStructured Text. It is the standard markup language used for documenting python packages. Sphinx is the Python package that generates an html website from RST files, and it is what we are using to generate this site.


1 Answers

I figured out a way to do this while looking at something else.

There are functions autodoc will call before printing the message. I added this code to my conf.py file:

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)

I want to use the | token, but they are reserved for global substitutions. I got around that by putting the following line my rst file (so the code substitutes |class| for |class|):

.. |class| replace:: `|class|`
like image 68
Charles L. Avatar answered Oct 05 '22 07:10

Charles L.