Python Sphinx z długimi nazwami

Question

Pracuję nad dokumentacją dla mojego modułu Pythona (używając Sphinx i reST), i znajduję to, gdy porównując inne obiekty Pythona (moduły, klasy, funkcje, itp.), Cały obiekt nazwa kończy się niesamowicie długa. Często jest to więcej niż 80 znaków, których chciałbym uniknąć za wszelką cenę.

Oto przykład:

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

    ''' 

Kwestia jest taka, że ​​przy tworzeniu dokumentacji dla ReallyLongExampleClassName klasy I generowane go do pełna nazwa ścieżki module1.module2.module3.module4.module5.ReallyLongExampleClassaName .

Zastanawiam się, czy jest jakiś sposób, aby rozwiązać ten problem? Próbowałem następujących metod, bez powodzenia:

1) Dodawanie podział na linii w środku nazwy modułu. Przykład:

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

2) Odniesienie do nazwy klasy w inny (ale wciąż możliwy do importowania w Pythonie sposób). Przykład:

:class:`module1.module2.ReallyLongClassName` 

wierzę, że skoro dokumentacja ReallyLongClassName jest przywiązany do pełnych nazw ścieżek że Sfinks nie można skorelować skróconej wersji z wersją całkowicie nazwie.

Każda pomoc zostanie bardzo doceniona.

Edit 04/05/2012:

Jak na odpowiedź/sugestię j13r (patrz niżej) Próbowałem następujące:

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

I to działało poprawnie. Jedynym zastrzeżeniem, aby to zadziałało, jest to, że druga linia nie może zawierać spacji (co jest dość frustrujące, gdy używa się tego w docstringu). Tak więc, aby mój oryginalny przykład zadziałał, wyglądałby tak:

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

    ''' 

Ładnie i brzydko. Jeśli wstawisz spacje przed "ReallyLongExampleClassName" w celu wcięcia go na ten sam poziom, co linia powyżej, wynik będzie zawierać spacje, a zatem Sphinx spróbuje odwołać się do czegoś takiego jak "module1.module2.module3.module4.module5. ReallyLongExampleClassName. "

Należy również pamiętać, że próbowałem dwie inne odmiany tego, co nie działa:

# 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` 

szukałem rozwiązania, które nie wiążą się niszcząc formatowanie docstring, ale przypuszczam, to zrobi ... Myślę, że tak naprawdę wolę linię, która ma ponad 80 znaków.

Dzięki j13r za odpowiedź!

Answer 1

Zgodnie z dokumentacją sfinks (http://sphinx.pocoo.org/domains.html?highlight=current#cross-referencing-python-objects) można wykorzystać kropkę przed klasy docelowej:

:class:`.ReallyLongExampleClassName` 

lub

:class:`.module5.ReallyLongExampleClassName` 

i niech sfinks wyszukiwania dla klasy:

... jeśli nazwa jest poprzedzona kropką i bez dokładnego dopasowania zostanie znaleziony, cel jest brane jako przyrostek i wszystkie nazwy obiektów z tym sufiksem są przeszukiwane . Na przykład: py: meth: .TarFile.close odwołuje się do funkcji tarfile.TarFile.close(), nawet jeśli bieżący moduł nie jest tarfile. Ponieważ może to być niejednoznaczne, jeśli istnieje więcej niż jedno możliwe dopasowanie, otrzymasz ostrzeżenie od Sphinx.

Answer 2

Dzikie stab w ciemności.Może to działa:

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

Byłoby ważne Python

import scipy.\ 
stats 

Answer 3

Możesz użyć ~ jako prefiksu, robi dokładnie to, co chcesz.

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

Answer 4

Inną strategią jest użycie reszta Substitutions. To pozwoli Ci zaoszczędzić więcej miejsca w tekście poprzez wywołanie odsyłacza :class: później:

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

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

    ''' 

Jeśli odnoszące się do tej samej klasy w wielu plikach, można zamiast tego umieścić w swojej podstawienie Sphinx conf.py, używając ustawienia rst_epilog. Z dokumentacji Sphinx:

rst_epilog

ciąg reStructuredText które zostaną zawarte na końcu każdego pliku źródłowego, który jest odczytywany. Jest to właściwe miejsce na dodawanie podstawień, które powinny być dostępne w każdym pliku. Przykład:

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

Nowość w wersji 0.6.

Wtedy twój docstring będzie tylko:

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

    '''