Используя Sphinx с поддержкой домена ObjectDescription s Я могу создать для них необычную документацию.Например:
.. py:function:: pyfunc()
Describes a Python function.
Это хорошо отображает контент, и это очень хорошо работает с индексами модулей, ссылками и так далее.Круто, пока!
Теперь, допустим, у меня есть эта директива в исходном документе src/mymodule/functions.rst, и у меня есть набор текста в src/guide/getting-started.rst, я могу ссылаться на такие объекты, как
:py:func:`pyfunc`
Тоже круто!
Теперь мой актуальный вопрос;Могу ли я также попросить автора Sphinx перерисовать тот же фрагмент документации для этого объекта?Чтобы избавить пользователя от необходимости переходить со страницы «Начало работы», где я просто хочу снова включить один фрагмент контента.
Что я пытался сделать:
- Просто скопируйте содержимое.Это приводит к предупреждению о том, что объект определяется несколько раз, наносит ущерб индексу и в результате ссылки не указывают на «авторитетное» место в вашем проекте, если ему не повезло.Не все в порядке.
- Документируйте каждый объект в отдельном файле, а затем используйте
.. include:: rel/path/to/pyfunc.rst в каждом документе, где я хочу его визуализировать.Поскольку эти включения являются буквальными на уровне ReST, это приводит к тем же недостаткам, что и опция выше.: - (
Таким образом, я ищу решение, в котором я бы сказал, чтобы средство визуализации / записи Sphinx просто перерисовывало содержимое ссылки вместо создания ссылки. Оно не должнодобавьте его в индекс для простого повторного рендеринга.
У меня все в порядке с пользовательским расширением или пользовательским решением для конкретного домена - я уже использую свой собственный пользовательский домен, но я просто использовал общийПриведенный выше домен Python в качестве известного примера.
Контекст для варианта использования: я создаю домен Protobuf. Сообщения и перечисления Protobuf многократно используются, и я хотел бы показатьконтекст часто используемых объектов, встроенный на страницах, где это полезно для читателя. Это означает, что он повторяется для всего проекта специально, где он считается полезным, а не перемещается все время. Однако только справочная страница должна быть «авторитетной»".