Python Sphinx che fa riferimento ai nomi lunghi

Question

Sto lavorando alla documentazione per il mio modulo Python (usando Sphinx e reST), e sto scoprendo che quando si incrociano riferimenti ad altri oggetti Python (moduli, classi, funzioni, ecc.) L'oggetto completo il nome finisce per essere incredibilmente lungo. Spesso è più lungo di 80 caratteri, che vorrei evitare a tutti i costi.

Ecco un esempio:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    :class:`module1.module2.module3.module4.module5.ReallyLongExampleClassName` 

    ''' 

Il problema è che quando si crea la documentazione per la classe diReallyLongExampleClassName, ho generato per il percorso completo module1.module2.module3.module4.module5.ReallyLongExampleClassaName .

Mi chiedo se esiste un modo per risolvere questo problema? Ho provato i seguenti metodi, senza successo:

1) Aggiunta di un'interruzione di riga nel mezzo del nome del modulo. Esempio:

:class:`module1.module2.module3.module4. 
module5.ReallyLongExampleClassName` 

2) Fare riferimento al nome della classe in un modo diverso (ma ancora impossibile da Python). Esempio:

:class:`module1.module2.ReallyLongClassName` 

Credo che dal momento che la documentazione per ReallyLongClassName è legata ai nomi di percorso completo che Sfinge non può correlare la versione abbreviata con la versione completamente di nome.

Qualsiasi aiuto sarà molto apprezzato.

Edit 04/05/2012:

Come per la risposta/suggerimento del j13r (vedi sotto) ho provato la seguente:

:class:`module1.module2.module3.module4.module5\ 
ReallyLongExampleClassName` 

E questo ha funzionato con successo. L'unica avvertenza per far funzionare tutto questo è che la seconda riga non deve avere spazi prima di essa (il che è piuttosto frustrante quando si usa questo in una docstring). Così per far funzionare il mio esempio originale sarebbe come:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    :class:`module1.module2.module3.module4.module5.\ 
ReallyLongExampleClassName` 

    ''' 

Bello e brutto. Se dovessi inserire spazi prima di "ReallyLongExampleClassName" per indentarlo allo stesso livello della riga sopra di esso, l'output includerebbe gli spazi e pertanto Sphinx proverebbe a fare riferimento a qualcosa come "module1.module2.module3.module4.module5. ReallyLongExampleClassName. "

Vorrei anche sottolineare che ho provato altre due varianti di questo, che non ha funzionato:

# Note: Trying to put a space before the '\' 
    :class:`module1.module2.module3.module4.module5. \ 
ReallyLongExampleClassName` 

    # Note: Trying to leave out the '\' 
    :class:`module1.module2.module3.module4.module5. 
ReallyLongExampleClassName` 

ero alla ricerca di una soluzione che non ha comportato distruggere la formattazione del docstring, ma suppongo lo farà ... Penso che in realtà preferisco una linea che superi gli 80 caratteri a questo.

Grazie a j13r per la risposta!

Answer 1

Secondo la documentazione sfinge (http://sphinx.pocoo.org/domains.html?highlight=current#cross-referencing-python-objects) è possibile utilizzare un punto prima della classe di destinazione:

:class:`.ReallyLongExampleClassName` 

o

:class:`.module5.ReallyLongExampleClassName` 

e lasciare di ricerca sfinge per la classe:

... se il nome è preceduto da un punto, e nessuna corrispondenza esatta viene trovato, il bersaglio è preso come un suffisso e tutti i nomi degli oggetti con il suffisso che vengono ricercati . Ad esempio: py: meth: .TarFile.close fa riferimento alla funzione tarfile.TarFile.close(), anche se il modulo corrente non è tarfile. Dato che questo può diventare ambiguo, se c'è più di una possibile corrispondenza, riceverai un avvertimento da Sphinx.

Answer 2

Pugnale selvaggio nel buio.Forse questo funziona:

:class:`module1.module2.module3.module4.\ 
module5.ReallyLongExampleClassName` 

Sarebbe valida Python

import scipy.\ 
stats 

Answer 3

È possibile utilizzare ~ come prefisso, fa esattamente ciò che si desidera.

http://sphinx-doc.org/markup/inline.html#xref-syntax

Answer 4

Un'altra strategia è quello di utilizzare reST Substitutions. Questo vi permetterà di risparmiare più spazio nel testo chiamando il :class: riferimento incrociato più tardi:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    |ReallyLongExampleClassName| 

    .. |ReallyLongExampleClassName| replace:: 
            :class:`.ReallyLongExampleClassName` 

    ''' 

Se ti riferisci alla stessa classe in molti dei vostri file, si potrebbe invece mettere la sostituzione nella vostra File conf.py di Sphinx, usando l'impostazione rst_epilog. Dalla documentazione Sfinge:

rst_epilog

Una stringa di reStructuredText che verrà incluso alla fine di ogni file di origine che viene letto. Questo è il posto giusto per aggiungere sostituzioni che dovrebbero essere disponibili in ogni file. Un esempio:

rst_epilog = """ 
.. |psf| replace:: Python Software Foundation 
""" 

Nuovo nella versione 0.6.

Allora il vostro docstring sarebbe solo:

def exampleFunction(): 
    '''Here is an example docstring referencing another 
    |ReallyLongExampleClassName| 

    '''