首页 文章

Sphinx autodoc不够自动化

提问于
浏览 次
135

我正在尝试使用Sphinx来记录Python中的5000行项目 . 它有大约7个基本模块 . 据我所知，为了使用autodoc我需要为我的项目中的每个文件编写这样的代码：

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

这太繁琐了，因为我有很多文件 . 如果我能指定我想要记录'mods'包，那将会容易得多 . 然后，Sphinx可以递归地遍历包并为每个子模块创建一个页面 .

有这样的功能吗？如果没有，我可以写一个脚本来制作所有的.rst文件，但这会花费很多时间 .

python python-sphinx

4 回答

  • 1

    你可以查看我做过的这个script . 我认为它可以帮到你 .

    此脚本解析目录树以查找python模块和包，并相应地创建ReST文件以使用Sphinx创建代码文档 . 它还创建了一个模块索引 .

    UPDATE

    此脚本现在是Sphinx 1.1的一部分apidoc .

    回复于
  • 31

    我不知道Sphinx在询问原始问题的时候是否有autosummary扩展，但是现在很有可能在不使用 sphinx-apidoc 或类似脚本的情况下设置这种类型的自动生成 . 下面有一些设置适用于我的一个项目 .

    • 在 conf.py 文件中启用 autosummary 扩展名（以及 autodoc ）并将其 autosummary_generate 选项设置为 True . 如果您不使用自定义 *.rst 模板，这可能就足够了 . 否则，将模板目录添加到排除列表，或 autosummary 将尝试将它们视为输入文件（这似乎是一个错误） .
    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']
autosummary_generate = True
templates_path = [ '_templates' ]
exclude_patterns = ['_build', '_templates']
    • 在 index.rst 文件的TOC树中使用 autosummary:: . 在此示例中，模块 project.module1 和 project.module2 的文档将自动生成并放入 _autosummary 目录中 .
    PROJECT
=======

.. toctree::

.. autosummary::
   :toctree: _autosummary

   project.module1
   project.module2
    • 默认情况下 autosummary 将仅为模块及其功能生成非常短的摘要 . 要更改它，您可以将自定义模板文件放入 _templates/autosummary/module.rst （将使用Jinja2进行解析）：
    {{ fullname }}
{{ underline }}

.. automodule:: {{ fullname }}
    :members:

    总之，没有必要在版本控制下保留 _autosummary 目录 . 此外，您可以将其命名为任何名称，并将其放置在源树中的任何位置（尽管如此，将它放在 _build 下面也不会起作用） .

    回复于
  • 127

    在每个包中， __init__.py 文件可以包含每个部分的 .. automodule:: package.module 组件 .

    然后你可以 .. automodule:: package 它主要做你想要的 .

    回复于
  • 11

    也许你正在寻找的是Epydoc和这个Sphinx extension .

    回复于

相关问题