Могу ли я зарегистрировать в Sphinx несколько ключевых слов, которые всегда следует переводить в ссылки?

Question

Мои строки документации имеют ссылки на другие классы Python, которые я определил. Каждый раз, когда Sphinx встречает один из этих классов, я хочу, чтобы он вставлял ссылку на документацию для этого другого класса. Возможно ли это в сфинксе?

В частности, у меня есть строка документа вроде:

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

Я мог бы написать:

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

но я бы предпочел, чтобы Sphinx нашел весь текст, соответствующий Foo, и выглядело бы так, как будто я набрал : Класс: ~foo.Foo

Answer 1

Вы можете использовать макросы.

В моем проекте у меня есть заголовочный файл, который содержит все «важные» классы и глобальные функции и их аббревиатуру. Две строки примера:

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

В мои rst файлы я включаю этот заголовочный файл. Тогда я могу использовать макросы в любом rst файле:

.. include:: defs.hrst

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

(Вы также можете включить строки документации из исходных файлов Python, используя расширение autogen. Макросы в них также будут заменены.)

О вашем примере: я бы добавил Foo в заголовочный файл и написал бы строку документации следующим образом:

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

Answer 2

Сфинкс имеет огромное количество интерпретируемых текстовых ролей для этого.

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

Я хочу войти в Foo и заставить Сфинкса интерпретировать его так, как если бы я написал: class: ~foo.Foo

Это звучит непрактично. Похоже, это парализует RST, пытаясь разобрать ваш текст. Поиск интерпретированного текста и нескольких правил цитирования, которые поддерживает RST (*_|`), - это практический предел.

То, что вы просите, может привести к тому, что RST потратит целый день на проверку каждого экземпляра Foo во всех возможных контекстах и ​​выяснит, хотите ли вы ссылку или нет. Вы хотели бы это только в других случаях - Foo; тривиальный поиск и замена не будут работать.

Вы можете возиться с предварительной обработкой документации.

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

Это может позволить вам попробовать глобальную стратегию поиска и замены в вашем текстовом документе.