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          


        

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.