python - Override function declaration in autodoc for sphinx

Question

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.)

Answer 1

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.