Каково использование setup(app) в conf.py?
Я видел несколько функций в Sphinx, которые определяют функцию setup(app), например «Предварительная обработка строки документа» функции расширения autodoc.
Я пытался найти API для setup(app), но результаты меня не полностью просветили. Я нашел это краткое объяснение:
Каждое расширение Sphinx представляет собой модуль Python, по крайней мере, с функцией setup(). Эта функция вызывается во время инициализации с одним аргументом — объектом приложения, представляющим процесс Sphinx.
Есть и такое объяснение:
Разработка расширений для Sphinx
При выполнении
sphinx-buildSphinx попытается импортировать каждый модуль из списка и выполнитьyourmodule.setup(app). Эта функция используется для подготовки расширения (например, путем выполнения кода Python), связывания ресурсов, которые Sphinx использует в процессе сборки (таких как файлы CSS или HTML), и уведомления Sphinx обо всем, что предлагает расширение (например, определения директив или ролей). . Аргументappявляется экземпляром Sphinx и дает вам контроль над большинством аспектов сборки Sphinx.
И, наконец, это объяснение:
Эти события известны до мозга костей. Показанные аргументы передаются зарегистрированным обработчикам событий. Используйте
Sphinx.connect()в функцииsetupрасширения (обратите внимание, чтоconf.pyтакже может иметь функцию настройки), чтобы подключить обработчики к событиям.
Итак, мой вопрос заключается в том, является ли единственное использование setup(app) в conf.py подключением обработчиков событий к основным событиям Sphinx через функцию Sphinx.connect(event, callback)? Или я что-то упускаю? Все остальные варианты использования setup(app) ограничены написанием пользовательских расширений?
P.S. Adding confusion the setup reserved word is also used by "Setuptools integration" , and searching the documentation there are several occurrences. I suppose this is an unrelated coincidence of using the same name.
Ответы 1
Оба. Вы можете использовать setup() либо в вашем conf.py, либо в расширении Sphinx, которое также является модулем Python. Это дело Python. пример использования в документации Pyramid и вы можете найти аналогичный в расширениях Sphinx. В документации Sphinx тоже есть пример:
# The registration function
def setup_my_func(app, pagename, templatename, context, doctree):
# The template function
def my_func(mystring):
return "Your string is %s" % mystring
# Add it to the page's context
context['my_func'] = my_func
# Your extension's setup function
def setup(app):
app.connect("html-page-context", setup_my_func)
Теперь у вас будет доступ к этой функции в jinja следующим образом:
<div>
{{ my_func("some string") }}
</div>
Оба. Вы можете использовать
setup()либо в своемconf.py, либо в расширении Sphinx, которое также является модулем Python. Это дело Python. пример использования в документации Pyramid и вы можете найти аналогичный в расширениях Sphinx. В документации Sphinx тоже есть пример.