Kann ich bei Sphinx eine Reihe von Keywords registrieren, die immer in Links übersetzt werden sollen?

Question

Meine Doc-Strings haben Verweise auf andere Python-Klassen, die ich definiert habe. Jedes Mal, wenn Sphinx auf eine dieser Klassen stößt, möchte ich, dass es eine Verknüpfung zur Dokumentation für diese andere Klasse einfügt. Ist das bei Sphinx möglich?

Insbesondere, ich habe einen doc-String wie:

'''This class contains a bunch of Foo objects''' 

konnte ich schreiben:

'''This class contains a bunch of :class:`~foo.Foo` objects''' 

aber ich würde es vorziehen, dass Sphinx alle Text Foo passend findet und mache es den Anschein, als ob ich hatte typisierte : Klasse: ~foo.Foo

Answer 1

Sie können Makros verwenden.

In meinem Projekt habe ich eine Header-Datei, die alle "wichtigen" Klassen und globalen Funktionen und ihre Abkürzung enthält. Zwei Beispielzeilen:

.. |PostItem| replace:: :class:`PostItem <hklib.PostItem>` 
.. |PostNotFoundError| replace:: :class:`PostNotFoundError <hklib.PostNotFoundError>` 

In meinen rst Dateien, ich um diese Header-Datei. Dann kann ich die Makros in jeder rst Datei:

.. include:: defs.hrst 

|PostItem| is a nice class. |PostNotFoundError|, on the other hand is not. 

(.. Sie Docstrings von Python-Source-Dateien auch enthalten können, mit der autogen Erweiterung Makros in denen wird auch ersetzt werden)

Über Ihr Beispiel: Ich würde Foo der Header-Datei hinzufügen und den Docstring folgendermaßen schreiben:

'''This class contains a bunch of |Foo| objects''' 

Answer 2

Sphinx hat eine große Anzahl von interpretierten Textrollen dafür.

http://sphinx.pocoo.org/markup/inline.html#cross-referencing-python-objects

Ich möchte Foo betreten und haben Sphinx es interpretieren, als ob ich geschrieben hatte: Klasse: ~foo.Foo

dies praktisch nicht möglich klingt. Es scheint, als würde es RST paralysieren, indem es versucht, Ihren Text zu parsen. Auf der Suche nach interpretiertem Text und den wenigen Zitationsregeln, die RST unterstützt (*_|`), geht es um die Grenze, die praktisch ist.

Was Sie fordern, könnte dazu führen, dass RST den ganzen Tag braucht, um jede Instanz Foo in jedem möglichen Kontext zu überprüfen und herauszufinden, ob Sie eine Verbindung wollten oder nicht. Sie möchten dies nur in ansonsten nicht dekorierten Instanzen von Foo; triviales Suchen und Ersetzen würde nicht funktionieren.

Sie können mit der Docstring-Vorverarbeitung herumhantieren.

http://sphinx.pocoo.org/ext/autodoc.html#docstring-preprocessing

Dies kann Ihnen erlauben, eine globale Suche-und-Ersetzen-Strategie auf Ihrem docstring Text zu versuchen.