sphinxcontrib-kissapi 1.0.3

为什么要使用这个插件？

此插件采用与autoapi、 automodapi或普通 autodoc等其他插件不同的方法。我发现这些其他插件在自动生成 API 文档方面做得很好，但它从来都不是完美的。他们不会确切地知道文档中要包含什么，而且没有足够的自定义选项来获得我需要的东西。

这个插件不是自动生成文档，而是提供了一个简单、灵活的 API 来分析和内省你的 python 代码。使用 API，您可以根据需要自行生成 reST 文档！保持简单，愚蠢。

我还包括一个默认的“渲染器”，它将自动生成 reST 文档。如果您对输出感到满意并且不需要任何额外的自定义，则可以使用它。

用法

通过 pip 安装包。另请参阅github 上的源代码以手动构建。

pip install sphinxcontrib-kissapi

在你的 sphinx conf.py文件中，首先将sphinxcontrib.kissapi添加到extensions。KissAPI 被集成以使用 sphinx 的内置autodoc和autosummary来提取自省变量的文档（如果需要），因此您也需要添加这些依赖项。

其次，我们需要配置 KissAPI 应该自省哪些包以及您希望如何呈现该包数据。这是通过在Kissapi_config dict 变量中设置选项来配置的。支持以下选项：

out_dir str

渲染器生成的文件的输出目录。默认值为"kissapi_output"。

覆盖

是否覆盖out_dir。这可以是三个值之一：

1. True : 删除文件夹并完全重建

2. False : 如果找到文件夹不做任何事情，保持原样

3. "partial" : 允许文件被覆盖，但不要完全删除out_dir

jinja_dir str

一个带有 jinja 模板的目录，它允许您在RenderManager类上使用一些帮助程序，以便更轻松地生成 reST 文件。如果给出了相对路径，它将相对于 sphinx 根 docs 文件夹。默认情况下，它设置为sphinxcontrib/kissapi/def_templates目录，这是我与默认渲染器 ( sphinxcontrib.kissapi.def_render )一起制作的一些默认 jinja 模板。

jinja_env

使用自定义 Jinja 环境，而不是使用jinja_dir。

输出字典

这是用于指定要生成的自动文档的主要配置选项。此 dict 是从唯一输出名称到输出配置选项的映射：{out_name: out_config, ...}。配置选项也是一个字典，具有以下值：

• package (str)：要自省和渲染的包。请参阅自省配置值以自定义自省行为。提供模块名称作为字符串。

• render (callable): 带有签名的回调(mgr:RenderManager, pkg:PackageAPI)。第二个参数是包的自省结果，您可以使用它的 API 来检查模块、类、函数、变量以及它们的相关信息。RenderManager实例有几种方法可以帮助您编写 reST 文件并使用您的 jinja 模板。

  如果您愿意，回调可以返回一个字符串或 reST 节点列表，这些节点应该作为out_name存储在RenderManager中。这些可以稍后注入到您预先存在的 reST 文档中。但是，这不是必需的。

  如何渲染包完全取决于您。我为我的一个项目编写的默认渲染器可在sphinxcontrib.kissapi.def_render.pkg_template 获得，我对它生成的文档感到满意。随意为您自己的项目使用或修改它。

内省字典

指定用于自定义如何自省包的选项。与output类似，它是从包名称到配置选项的映射：{package_name: introspect_config, ...}。配置选项被指定为具有以下可选值的 dict：

• package_exclude：带有签名的回调(pkg_name:str, module_name:str) -> bool。如果模块（例如来自sys.modules的模块）应该从包中排除并标记为“外部”模块，它应该返回True 。您还可以返回任何其他真实值以排除模块，但不要将其标记为外部。当is_external被调用时，在你的包和外部模块中引用的变量将显示为 True 。

  如果未提供此回调，则使用PackageAPI.default_package_exclude；此默认方法排除不以“[pkg_name]”为前缀的模块。，或在路径中的某处包含私有模块（例如，以下划线为前缀，例如mypackage._private.submodule）。请注意，只有非排除模块会被 KissAPI 内省。

• var_exclude：带有签名的回调(pkg:PackageAPI, parent:VariableValueAPI, value:VariableValueAPI, name:str) -> bool。KissAPI 使用变量引用的概念，即父上下文和变量引用名称。例如，在下面的代码片段中，有两个对 list [1,2,3]的引用：

  baz = [1,2,3]
  class Foo:
      bar = baz

  第一个引用在名为baz的模块本身的全局变量中。第二个参考在类Foo中，名称为bar。此示例中的“父级”是模块或类；“值”是[1,2,3]；“名称”是baz或bar，具体取决于父级。

  此选项允许您指定应分析哪些变量引用以及应跳过哪些变量引用。默认情况下，如果未提供，则使用PackageAPI.default_var_exclude；此默认方法不包括私有（以单个下划线为前缀）和外部（在非包模块中检测到）变量。

总而言之，这是您可能放入conf.py的代码示例：

extensions = ["sphinx.ext.autodoc","sphinx.ext.autosummary","sphinxcontrib.kissapi",'sphinx_rtd_theme']

from sphinxcontrib.kissapi.def_render import package_template
kissapi_config = {
    "overwrite": True,
    "output": {
        "my_rendered_output":{
            "package":"my_package",
            "render":package_template
        }
    }
}

如果渲染回调要输出值，则可以使用 Kissapi指令在现有的 reST 文档中引用它们。对于上面的conf.py示例，我们可以通过在某处添加此指令来注入“my_rendered_output”：

.. kissapi:: my_rendered_output