Я пытаюсь использовать sphinx.ext.autosummary документировать пакет Python. Поскольку «автосводка» требует, чтобы мы перечислили все элементы, которые должны быть включены, я хотел указать их с помощью Jinja2.
Мой conf.py выглядит следующим образом (показаны соответствующие части):
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.autosummary',
'sphinx.ext.doctest',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.viewcode',
'sphinx.ext.napoleon',
'sphinx_automodapi.automodapi'
]
autodoc_default_options = {
'imported-members':True
}
add_module_names = False
autosummary_generate = True
numpydoc_show_class_members = False
def rstjinja(app, docname, source):
"""
Render our pages as a jinja template for fancy templating goodness.
"""
# Make sure we're outputting HTML
if app.builder.format != 'html':
return
src = source[0]
rendered = app.builder.templates.render_string(
src, app.config.html_context
)
source[0] = rendered
def setup(app):
app.connect("source-read", rstjinja)
# in actual usage, `entities` is determined at docs generation time via some code
html_context = {
'entities' : ["classA", "classB", "classD"]
}
Методы rstjinja() и setup() были заимствованы из здесь . В нем четко указано, что:
Шаблоны Jinja будут обработаны до обработки RST.
Мой .rst файл выглядит следующим образом:
#####
Title
#####
.. currentmodule:: Package.SubModule
.. autosummary::
:nosignatures:
:toctree:
{% for item in entities %}
{{ item }}
{% endfor %}
Вывод правильно показывает мне сводную таблицу, состоящую из 3 записей (по одной для каждого из трех указанных мною классов: «classA», «classB», «classD»). В первом столбце отображается имя класса, а во втором столбце - однострочное описание (из его строки документации). Данные во втором столбце ясно показывают, что Sphinx может идентифицировать соответствующие классы и извлекать их строки документации.
Моя проблема в том, что «автосуммари» не создает заглушек для этих классов, и поэтому эти записи в таблице нельзя щелкнуть. На терминале я вижу следующее предупреждение для каждого из классов с отсутствующими заглушками:
ВНИМАНИЕ: autosummary: файл-заглушка «Package.SubModule.classA» не найден. Проверьте настройку autosummary_generate.
Как видно из моего файла conf.py, этот параметр уже True.
Если я изменю (ради изучения) файл .rst на следующее:
#####
Title
#####
.. currentmodule:: Package.SubModule
.. autosummary::
:nosignatures:
:toctree:
{% for item in entities %}
{{ item }}
{% endfor %}
classA
Затем я получаю таблицу, аналогичную предыдущему случаю, но с дополнительной строкой в конце, соответствующей «classA». И что интересно, обе записи для «classA» (первая сгенерирована с помощью Jinja, вторая с помощью явного указания) теперь гиперссылки на заглушку, созданную для «classA».
Почему это так? Почему не создаются заглушки, когда одна и та же информация указывается только через Jinja (хотя sphinx действительно отображает строки документации для них в таблице)?
Как я могу решить эту проблему? Для меня важно иметь возможность предоставить список сущностей, которые нужно документировать с помощью Jinja (поскольку я определяю их с помощью некоторого кода Python в conf.py).
Дополнительная информация: в приведенном выше примере классы можно импортировать через
from Package.SubModule import classA, classB, classD
html_context. Что вы получаете, используя Jinja? - person mzjn schedule 20.12.2019html_context, но при фактическом использовании они определяются с помощью некоторого кода. 2) У нас есть набор похожих пакетов, и мы хотим иметь общий сценарий, который будет обрабатывать документацию для каждого из этих модулей. Имена записей, подлежащих документированию, могут различаться в этих пакетах, но мы бы хотели избежать ручного редактирования. - person Shailesh Appukuttan schedule 20.12.2019