У Сфинкса я могу зарегистрировать набор ключевых слов, которые должны всегда переводиться в ссылки?
Мои строки документа имеют ссылки на другие классы Python, которые я определил. Каждый раз, когда Сфинкс встречается с одним из этих классов, я хочу, чтобы он вставил ссылку на документацию для того другого класса. Действительно ли это возможно у Сфинкса?
А именно, у меня есть строка документа как:
'''This class contains a bunch of Foo objects'''
Я мог записать:
'''This class contains a bunch of :class:`~foo.Foo` objects'''
но я предпочел бы, чтобы Сфинкс нашел все текстовое соответствие Foo и заставляет его казаться, как будто я ввел: класс:~foo.Foo
2 ответа
Вы могут использовать макросы.
В моем проекте у меня есть файл заголовка, который содержит все «важные» классы и глобальные функции и их сокращения. Две строки примера:
.. |PostItem| replace:: :class:`PostItem <hklib.PostItem>`
.. |PostNotFoundError| replace:: :class:`PostNotFoundError <hklib.PostNotFoundError>`
В мои файлы 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'''
Для этого у Sphinx есть огромное количество интерпретируемых текстовых ролей.
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
Это может позволить вам попробовать глобальную стратегию поиска и замены в тексте строки документации.