Aufschalten Funktionsdeklaration in Autodoc für Sphinx

Question

Ich habe ein Modul, das etwas geht:

#!/usr/bin/env python 

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

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

... und ich habe eine .rst-Datei, die etwas geht:

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

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

Wenn Ich erstelle die Dokumentation, ich bekomme eine HTML-Datei mit einem Ausschnitt, der so lautet:

mymodule.foobar. foobar = 'Einige absurder lang und hässlich regex hier'

Zusätzliche Dokumentation hier

mymodule. myfunc (val = 'Einige absurder lang und hässlich regex hier')

blablabla

Basierend auf dieser stackoverflow post, ich dachte, dass ich es durch Ändern mein Modul ändern könnte:

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

... aber das hat nicht den Trick gemacht, und nur die Signatur, die ich wollte unter dem hässlichen als Teil des Körpers. Weiß jemand, wie ich das richtig übersteuern kann?

(Ich verwende Sphinx v1.1.3, btw.)

Answer 1

Sie haben eine Variable auf Modulebene, die als Standardwert eines Schlüsselwort-Argument in einer Funktion verwendet wird. Sphinx zeigt den Wert (anstelle des Namens) dieser Variablen in der Funktionssignatur an. Dieses Problem wird in another question diskutiert, und das OP hat auch an issue ticket bei GitHub darüber vorgelegt.

Sie können jedoch in zwei Möglichkeiten, um diese Arbeit:

1. Überschreiben Sie die Signatur in der .rst Datei von autofunction verwenden, wie in the answer auf die verknüpfte Frage erklärt.

2. Wenn die erste Zeile des docstring sieht aus wie eine Unterschrift, und wenn das autodoc_docstring_signature Konfigurationsvariable True gesetzt ist (was sie standardmäßig ist), so wird diese Linie Sphinx als Signatur verwendet werden.

   Wenn Sie also ein docstring haben, die wie folgt aussieht,

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

   es in der Art und Weise arbeiten, sollten Sie es wollen.

   In der Frage, haben Sie diese erste Zeile in der docstring:

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

   Das funktioniert nicht, weil es wie eine richtige Signatur sieht nicht aus.