python-3.x - 使用 Jinja2 和 Sphinx 自动摘要

Question

我正在尝试使用 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()借自 here .它明确指出:

The Jinja templates will be rendered before the RST is processed.

我的 .rst 文件如下:

#####
Title
#####

.. currentmodule:: Package.SubModule

.. autosummary::
    :nosignatures:
    :toctree:

    {% for item in entities %}
        {{ item }}
    {% endfor %}

输出正确地向我显示了一个包含 3 个条目的汇总表(我指定的三个类中的每一个:“classA”、“classB”、“classD”)。第一列显示类的名称，第二列显示一行描述(来自其文档字符串)。第二列中的数据清楚地表明 Sphinx 能够识别相关类并提取其文档字符串。

我的问题是“自动摘要”不会生成 stub 对于这些类，因此表中的这些条目不可点击。在终端上，我看到每个缺少 stub 的类的以下警告:

WARNING: autosummary: stub file not found 'Package.SubModule.classA'. Check your autosummary_generate setting.

正如在我的 conf.py 文件中看到的，这个设置已经是 True .

如果我(为了探索)将 .rst 文件更改为以下内容:

#####
Title
#####

.. currentmodule:: Package.SubModule

.. autosummary::
    :nosignatures:
    :toctree:

    {% for item in entities %}
        {{ item }}
    {% endfor %}
    classA

然后我得到一个类似于前一种情况的表，但在末尾有一个额外的行对应于“classA”。有趣的是，“classA”的两个条目(第一个通过 Jinja 生成，第二个通过显式指定)现在超链接到为“classA”创建的 stub 。

为什么会这样？当仅通过 Jinja 指定相同的信息时，为什么不创建 stub (即使 sphinx 确实在表中显示了这些信息的文档字符串)？

我该如何解决这个问题？能够通过 Jinja 提供要记录的实体列表对我来说很重要(因为我通过 conf.py 中的一些 Python 代码确定了这些)。

附加信息:
在上面的例子中，类可以通过
from Package.SubModule import classA, classB, classD

Answer 1

我找到了一个使用 sphinx_automodapi.automodapi 的解决方法延期。

我的相关内容 conf.py :

import sphinx_automodapi

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'sphinx_automodapi.automodapi'
]

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)


html_context = {
    'entities'       : ["classC", "classE"] # NOTE: specify classes NOT to be included/documented; items specified here will be skipped in doc generation
}

注意:通过 html_context 传递的类列表是要成为的类 排除 从文档中。如果扩展允许直接指定所需的类，那就太好了。我已经为相同的(目前未解决)开了一张票(这里: https://github.com/astropy/sphinx-automodapi/issues/92 )。

在实际使用中，类列表是可以动态确定的。例如:

import inspect, importlib, sciunit
package_import_name = "package_name"

submodule = "{}.submodule_name".format(package_import_name)
module = importlib.import_module(submodule)
exlcude_classes = [x[0] for x in inspect.getmembers(module,
                    lambda member: inspect.isclass(member)
                                    and not(<<specify condition>>))]

html_context = {
    'entities'       : exlcude_classes
}

我的 .rst 文件示例:

##########
Submodules
##########

.. automodapi:: package_name.submodule_name
    :nosignatures:
    :no-main-docstr:
    :skip: {{ entities|join(', ') }}