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.
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.
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.
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.
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.
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|`
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With