W Sphinx, czy mogę zarejestrować kilka słów kluczowych, które zawsze powinny być przetłumaczone na linki?

Question

Moje ciągi dokumentów zawierają odniesienia do innych klas Pythona, które zdefiniowałem. Za każdym razem, gdy Sphinx napotka jedną z tych klas, chcę wstawić link do dokumentacji tej innej klasy. Czy to możliwe w Sfinksie?

Konkretnie mam ciąg doc jak:

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

mógłbym napisać:

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

ale wolałbym że Sphinx znajdzie cały tekst pasujący Foo i sprawia, że ​​wydaje się, że miałem typ: : klasa: ~foo.Foo

Answer 1

Możesz użyć makr.

W moim projekcie mam plik nagłówkowy, który zawiera wszystkie "ważne" klasy i funkcje globalne oraz ich skrót. Dwie przykładowe linie:

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

W moich plikach rst uwzględniam ten plik nagłówkowy. Następnie można korzystać z makr w każdym rst pliku:

.. include:: defs.hrst 

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

(.. Można to docstrings z plików źródłowych Pythona, a także, poprzez rozszerzenie autogen Makra w te zostaną zastąpione również)

O Twój przykład: Dodałbym Foo do pliku nagłówka i napisałem w ten sposób docstring:

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

Answer 2

Sfinks ma ogromną liczbę interpretowanych ról tekstowych.

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

Chcę wprowadzić Foo i mają Sphinx interpretować go tak, jakbym pisał: Klasa: ~foo.Foo

Brzmi niepraktyczne. Wygląda na to, że sparaliżowałoby RST próbującego parsować twój tekst. Poszukując interpretowanego tekstu i kilku zasad cytowania, które obsługuje RST (*_|`), chodzi o limit, który jest praktyczny.

To, o co prosisz, może spowodować, że RST będzie cały dzień sprawdzać każdą instancję Foo w każdym możliwym kontekście i sprawdzać, czy chcesz mieć link, czy nie. Będziesz chciał tego tylko w niepoprawionych przypadkach: Foo; trywialne wyszukiwanie i zamienianie nie będzie działać.

Możesz zadzwonić z wstępnym przetwarzaniem docstring.

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

To może pozwolić, aby spróbować globalną strategię wyszukiwania i zamiany na tekst docstring.