In Sphinx, kann ich ein paar Schlüsselwörter registrieren, die immer in Links übersetzt werden sollen?

Question

Meine doc Strings haben Verweise auf andere Python-Klassen, die ich definiert haben. Jedes Mal, Sphinx begegnet einer dieser Klassen, ich habe es einen Link auf die Dokumentation für die andere Klasse eingefügt werden soll. Ist das möglich in Sphinx?

Insbesondere habe ich einen doc-String wie:

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

Ich könnte schreiben:

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

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

Answer 1

Sie können Makros verwenden.

In meinem Projekt habe ich eine Header-Datei, die alle „wichtige“ Klassen und globale Funktionen und deren Abkürzung enthält. Zwei Beispielzeilen:

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

In meiner rst Datei, 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 können auch Docstrings von Python-Source-Dateien enthalten, mit der autogen Erweiterung. Makros in denen werden auch ersetzt werden.)

Über Ihr Beispiel: Ich Foo in die Header-Datei hinzufügen würde und schreiben Sie die Docstring auf diese Weise:

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

Answer 2

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

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

  

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

Das klingt nicht praktikabel. Es scheint, wie es wäre RST lähmen Parsen Ihren Text zu versuchen. Suche nach interpretiert Text und die wenigen unter Angabe Regeln, dass RST Stützen (*_|`) ist über die Grenze, die praktisch ist.

Was Sie für Macht führen zu RST sind gefragt ganzen Tag nehmen jede Instanz Foo in jedem möglichen Zusammenhang und Vernunft, um zu überprüfen, ob Sie einen Link oder nicht erwünscht ist. Sie würden dies nur wollen in ansonsten undecorated Instanzen Foo; trivial suchen und ersetzen nicht funktionieren würde.

Sie können Chaos mit Docstring Vorbearbeitung.

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

Dies kann Ihnen erlauben, eine globale, um zu versuchen Such-und-Ersetzen-Strategie auf dem docstring Text.