Remplacer la déclaration de fonction dans l'autodoc pour sphinx

Question

J'ai un module qui fonctionne comme suit :

#!/usr/bin/env python

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

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

...et j'ai un .rst qui se présente comme suit :

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

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

Lorsque je crée la documentation, j'obtiens un fichier html avec un extrait qui ressemble à ceci :

mymodule.foobar. foobar \= 'Une regex absurdement longue et laide ici'

Documentation supplémentaire ici

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

blah blah blah

Sur la base de cette stackoverflow post J'ai pensé que je pouvais le modifier en changeant mon module en :

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

...mais cela n'a pas fonctionné, et j'ai juste ajouté la signature que je voulais sous la signature laide comme faisant partie du corps. Quelqu'un sait-il comment je peux modifier cela de manière appropriée ?

(J'utilise Sphinx v1.1.3, entre autres).

Answer 1

Vous avez une variable au niveau du module qui est utilisée comme valeur par défaut d'un argument de mot-clé dans une fonction. Sphinx affiche la valeur (au lieu du nom) de cette variable dans la signature de la fonction. Ce problème est abordé dans autre question et l'OP a également soumis un ticket d'incident sur GitHub à ce sujet.

Cependant, vous pouvez contourner ce problème de deux manières :

1. Remplacer la signature dans le fichier .rst en utilisant autofunction comme expliqué dans la réponse à la question posée.

2. Si la première ligne de la docstring ressemble à une signature et si l'élément autodoc_docstring_signature La variable de configuration est fixée à True (ce qui est le cas par défaut), Sphinx utilisera cette ligne comme signature.

   Ainsi, si vous avez une chaîne documentaire qui ressemble à ce qui suit,

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

   il devrait fonctionner comme vous le souhaitez.

   Dans la question, vous avez cette première ligne dans la docstring :

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

   Cela ne fonctionne pas, car cela ne ressemble pas à une signature en bonne et due forme.