Ich arbeite an der Dokumentation für mein Python-Modul (mit Sphinx und reST), und ich finde, dass beim Querverweisen auf andere Python-Objekte (Module, Klassen, Funktionen, usw.) der vollständige Objektname unglaublich ist lange. Oft sind es mehr als 80 Zeichen, die ich unbedingt vermeiden möchte.
Hier ist ein Beispiel:
%Vor%Das Problem ist, dass ich beim Erstellen der Dokumentation für die Klasse ReallyLongExampleClassName diese für den vollständigen Pfadnamen module1.module2.module3.module4.module5.ReallyLongExampleClassaName generiert habe.
Ich frage mich, ob es irgendeinen Weg gibt, das zu lösen? Ich habe die folgenden Methoden versucht, ohne Erfolg:
1) Einen Zeilenumbruch in der Mitte des Modulnamens hinzufügen. Beispiel:
%Vor%2) Verweis auf den Klassennamen in einer anderen (aber immer noch Python importierbaren) Weise. Beispiel:
%Vor%Ich glaube, da die Dokumentation für ReallyLongClassName an die vollständigen Pfadnamen gebunden ist, kann Sphinx die gekürzte Version nicht mit der vollständig benannten Version korrelieren.
Jede Hilfe wird sehr geschätzt.
Bearbeiten 04/05/2012 :
Gemäß der Antwort / Vorschlag von j13r (siehe unten) habe ich Folgendes versucht:
%Vor%Und das hat erfolgreich funktioniert. Die einzige Einschränkung, um dies zum Laufen zu bringen, ist, dass die zweite Zeile keine Leerzeichen davor haben darf (was ziemlich frustrierend ist, wenn man dies in einem Docstring verwendet). Um mein ursprüngliches Beispiel zu erstellen, würde es so aussehen:
%Vor%Nett und hässlich. Wenn Sie Leerzeichen vor "ReallyLongExampleClassName" setzen würden, um es auf die gleiche Ebene wie die darüber liegende Zeile einzufügen, würde die Ausgabe die Leerzeichen enthalten und Sphinx würde daher versuchen, auf etwas wie "module1.module2.module3.module4.module5. ReallyLongExampleClassName" zu verweisen. "
Ich sollte auch beachten, dass ich zwei andere Varianten ausprobiert habe, die NICHT funktionierten:
%Vor%Ich war auf der Suche nach einer Lösung, die nicht die Formatierung des Docstrings zerstört, aber ich denke, es wird ... Ich glaube, ich bevorzuge tatsächlich eine Zeile, die über 80 Zeichen überschreitet.
Danke an j13r für die Antwort!
Laut der Sphinx-Dokumentation ( Ссылка ) könnten Sie verwenden ein Punkt vor der Zielklasse:
%Vor%oder
%Vor%und lass Sphinx nach der Klasse suchen:
... Wenn dem Namen ein Punkt vorangestellt ist und keine exakte Übereinstimmung gefunden wird, wird das Ziel als Suffix verwendet und alle Objektnamen mit diesem Suffix werden durchsucht. Zum Beispiel: py: meth:
.TarFile.closeverweist auf die Funktion tarfile.TarFile.close (), auch wenn das aktuelle Modul nicht tarfile ist. Da dies mehrdeutig werden kann, erhalten Sie bei einer mehr als möglichen Übereinstimmung eine Warnung von Sphinx.
Sie können ~ als Präfix verwenden, es macht genau das, was Sie wollen.
Eine andere Strategie besteht darin, reST Ersetzungen zu verwenden. Dadurch können Sie mehr Platz im Text sparen, indem Sie später den :class: Querverweis aufrufen:
Wenn Sie in vielen Ihrer Dateien auf dieselbe Klasse verweisen, können Sie stattdessen die Substitution in Ihre Sphinx-Datei conf.py einfügen, indem Sie die rst_epilog Einstellung. Aus der Sphinx-Dokumentation:
rst_epilog
Eine reStructuredText-Zeichenfolge, die am Ende jeder gelesenen Quelldatei eingefügt wird. Dies ist der richtige Ort, um Substitutionen hinzuzufügen, die in jeder Datei verfügbar sein sollten. Ein Beispiel:
%Vor%Neu in Version 0.6.
Dann wäre dein Docstring einfach:
%Vor%Tags und Links python python-sphinx documentation restructuredtext