Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Override function declaration in autodoc for sphinx

I have a module that goes something like this:

#!/usr/bin/env python

#: Documentation here.
#: blah blah blah
foobar = r'Some really long regex here.'

def myfunc(val=foobar):
    '''Blah blah blah'''
    pass

...and I have a .rst file that goes something like this:

:mod:`my_module` Module
-----------------------

..automodule:: my_module
    :members:
    :private-members:
    :show-inheritance:

When I build the documentation, I get an html file with a snippet that goes like this:

mymodule.foobar.foobar = 'Some absurdly long and ugly regex here'

Extra documentation here

mymodule.myfunc(val='Some absurdly long and ugly regex here')

blah blah blah

Based on this stackoverflow post, I thought I could change it by altering my module to:

#!/usr/bin/env python

#: .. data:: my_module.foobar
#: Extra documentation here
foobar = 'Some really long regex here.'

def myfunc(val=foobar):
    '''.. function:: my_module.myfunc(val=foobar)

    Blah blah blah'''
    pass

...but that didn't do the trick, and just appended the signature I wanted under the ugly one as part of the body. Does anybody know how I can properly override this?

(I'm using Sphinx v1.1.3, btw.)

like image 374
Michael0x2a Avatar asked Aug 22 '12 23:08

Michael0x2a


People also ask

Does Sphinx use Docstrings?

Sphinx is a tool that transforms the docstrings in your code into beautiful, readable HTML files. It requires a one-time effort to set up and only one line of command to refresh the files (read till the end to find out how to refresh the files automatically!)

What is Sphinx Apidoc?

sphinx-apidoc is a tool for automatic generation of Sphinx sources that, using the autodoc extension, document a whole package in the style of other automatic API documentation tools. MODULE_PATH is the path to a Python package to document, and OUTPUT_PATH is the directory where the generated sources are placed.


1 Answers

You have a module-level variable that is used as the default value of a keyword argument in a function. Sphinx displays the value (instead of the name) of that variable in the function signature. This problem is discussed in another question, and the OP has also submitted an issue ticket at GitHub about it.

However, you can work around this in two ways:

  1. Override the signature in the .rst file by using autofunction, as explained in the answer to the linked question.

  2. If the first line of the docstring looks like a signature and if the autodoc_docstring_signature configuration variable is set to True (which it is by default), then Sphinx will use that line as the signature.

    So if you have a docstring that looks as follows,

    def myfunc(val=foobar):
        '''myfunc(val=foobar)
    
        Blah blah blah'''
        pass
    

    it should work in the way you want it.

    In the question, you have this first line in the docstring:

    .. function:: my_module.myfunc(val=foobar) 
    

    This does not work because it does not look like a proper signature.

like image 189
mzjn Avatar answered Oct 07 '22 11:10

mzjn