我正在尝试使用Sphinx在Python中记录一个5000多行的项目。它有大约7个基本模块。据我所知，为了使用autodoc，我需要为我的项目中的每个文件写这样的代码:
.. automodule:: mods.set.tests
:members:
:show-inheritance:
这太乏味了，因为我有很多文件。这将是更容易，如果我可以只是指定，我想要'mods'包被记录。然后，Sphinx可以递归地遍历包并为每个子模块创建一个页面。
有这样的功能吗?如果没有，我可以编写一个脚本来生成所有的.rst文件，但这将占用大量时间。
当前回答
我不知道Sphinx在最初的问题提出时是否有自动摘要扩展，但现在很有可能在不使用Sphinx -apidoc或类似脚本的情况下设置自动生成。下面是我的一个项目的设置。
Enable autosummary extension (as well as autodoc) in conf.py file and set its autosummary_generate option to True. This may be enough if you're not using custom *.rst templates. Otherwise add your templates directory to exclude list, or autosummary will try to treat them as input files (which seems to be a bug). extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary'] autosummary_generate = True templates_path = [ '_templates' ] exclude_patterns = ['_build', '_templates'] Use autosummary:: in TOC tree in your index.rst file. In this example documentation for modules project.module1 and project.module2 will be generated automatically and placed into _autosummary directory. PROJECT ======= .. toctree:: .. autosummary:: :toctree: _autosummary project.module1 project.module2 By default autosummary will generate only very short summaries for modules and their functions. To change that you can put a custom template file into _templates/autosummary/module.rst (which will be parsed with Jinja2): {{ fullname }} {{ underline }} .. automodule:: {{ fullname }} :members:
总之，没有必要将_autosummary目录置于版本控制之下。此外，您可以将其命名为任何您想要的名称，并将其放置在源树中的任何位置(但是，将其放在_build下面是行不通的)。
其他回答
在每个包中，__init__.py文件可以有..automodule:包。模块组件的每个部分的包。
然后你就可以…Automodule:: package，它主要做你想做的事情。
你可以看看我写的这个脚本。我想它对你有帮助。
这个脚本解析一个目录树，寻找python模块和包，并创建适当的ReST文件，以使用Sphinx创建代码文档。它还创建了一个模块索引。
更新
该脚本现在作为apidoc作为Sphinx 1.1的一部分。
也许你要找的是Epydoc和Sphinx扩展。
我不知道Sphinx在最初的问题提出时是否有自动摘要扩展，但现在很有可能在不使用Sphinx -apidoc或类似脚本的情况下设置自动生成。下面是我的一个项目的设置。
Enable autosummary extension (as well as autodoc) in conf.py file and set its autosummary_generate option to True. This may be enough if you're not using custom *.rst templates. Otherwise add your templates directory to exclude list, or autosummary will try to treat them as input files (which seems to be a bug). extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary'] autosummary_generate = True templates_path = [ '_templates' ] exclude_patterns = ['_build', '_templates'] Use autosummary:: in TOC tree in your index.rst file. In this example documentation for modules project.module1 and project.module2 will be generated automatically and placed into _autosummary directory. PROJECT ======= .. toctree:: .. autosummary:: :toctree: _autosummary project.module1 project.module2 By default autosummary will generate only very short summaries for modules and their functions. To change that you can put a custom template file into _templates/autosummary/module.rst (which will be parsed with Jinja2): {{ fullname }} {{ underline }} .. automodule:: {{ fullname }} :members:
总之，没有必要将_autosummary目录置于版本控制之下。此外，您可以将其命名为任何您想要的名称，并将其放置在源树中的任何位置(但是，将其放在_build下面是行不通的)。
Sphinx AutoAPI正是这样做的。
