Anulación declaración de la función en autodoc para esfinge

Question

tengo un módulo que es algo como esto:

#!/usr/bin/env python 

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

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

... y tengo un archivo .rst que dice algo como esto:

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

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

Cuando Construyo la documentación, obtengo un archivo html con un fragmento que dice así:

mymodule.foobar. foobar = 'Algunos absurdamente larga y desagradable expresión regular aquí'

documentación adicional aquí

mimodulo. myfunc (val = 'Algunos absurdamente larga y desagradable expresión regular aquí')

bla, bla, bla

En base a esta stackoverflow post, pensé que podía cambiarlo mediante la alteración de mi módulo para:

#!/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 

... pero eso no hace el truco, y acabamos de añadir la firma quería bajo la fea como parte del cuerpo. ¿Alguien sabe cómo puedo anular esto correctamente?

(estoy usando Sphinx v1.1.3, por cierto.)

Answer 1

tiene una variable de nivel de módulo que se utiliza como valor predeterminado de un argumento de palabra clave en una función. Sphinx muestra el valor (en lugar del nombre) de esa variable en la firma de la función. Este problema se discute en another question, y el OP también ha enviado an issue ticket en GitHub al respecto.

Sin embargo, puede solucionar de dos maneras:

1. Anular la firma en el archivo .rst utilizando autofunction, como se explica en the answer a la cuestión vinculada.

2. Si la primera línea de la cadena de documentación se ve como una firma y si la variable de configuración autodoc_docstring_signature se establece en True (que está por defecto), entonces Sphinx utilizará esa línea como la firma.

   Así que si usted tiene una cadena de documentación que se ve de la siguiente manera,

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

   que debería funcionar en la forma que desee.

   En la pregunta, que tienen esta primera línea en la cadena de documentación:

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

   Esto no funciona porque no se ve como una firma apropiada.