conf.py中setup(app)有什么用？

如何解决conf.py中setup(app)有什么用？

我在 Sphinx 中看到了几个定义 setup(app) 函数的功能，例如 autodoc 扩展的 "Docstring preprocessing" 功能。

我尝试寻找 setup(app) 的 API，但结果并没有完全启发我。我找到了这个简短的解释：

每个 Sphinx 扩展都是一个 Python 模块，至少有一个 setup() 函数。这个函数在初始化时被调用，带有一个参数，代表 Sphinx 进程的应用程序对象。

还有这样的解释：

执行 sphinx-build 时，Sphinx 将尝试导入列出的每个模块，并执行 yourmodule.setup(app)。此函数用于准备扩展（例如，通过执行 Python 代码），链接 Sphinx 在构建过程中使用的资源（如 CSS 或 HTML 文件），并通知 Sphinx 扩展提供的所有内容（例如指令或角色定义） . app 参数是 Sphinx 的一个实例，可让您控制 Sphinx 构建的大部分方面。

最后是这个解释：

Sphinx core events

这些事件是核心已知的。显示的参数提供给注册的事件处理程序。在扩展程序的 Sphinx.connect() 函数中使用 setup（注意 conf.py 也可以有设置函数）将处理程序连接到事件。

所以我的问题是，setup(app) 中 conf.py 的唯一用途是否是通过 Sphinx core events 函数将事件处理程序连接到 Sphinx.connect(event,callback)？或者我错过了什么？ setup(app) 的所有其他用途是否仅限于编写自定义扩展？

_{P.S. "Setuptools integration" 还使用了 setup 保留字，并搜索文档 there are several occurrences ，这增加了混淆。我想这是使用相同名称的一个不相关的巧合。}

解决方法

两者都有。你可以在你的 conf.py 或 Sphinx 扩展中使用 setup() ，它也恰好是一个 Python 模块。这是一个 Python 的东西。一个 example usage in Pyramid docs，你可以在 Sphinx 扩展中找到类似的。还有一个example in the Sphinx docs：

# 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>