我正在尝试使用Sphinx在Python中记录一个5000多行的项目。它有大约7个基本模块。据我所知，为了使用autodoc，我需要为我的项目中的每个文件写这样的代码:
.. automodule:: mods.set.tests
:members:
:show-inheritance:
这太乏味了，因为我有很多文件。这将是更容易，如果我可以只是指定，我想要'mods'包被记录。然后，Sphinx可以递归地遍历包并为每个子模块创建一个页面。
有这样的功能吗?如果没有，我可以编写一个脚本来生成所有的.rst文件，但这将占用大量时间。
当前回答
从Sphinx 3.1版(2020年6月)开始，Sphinx .ext.autosummary(终于!)具有自动递归。
因此，不再需要硬编码模块名称或依赖第三方库，如Sphinx AutoAPI或Sphinx autopackagsummarmary来进行自动包检测。
示例Python 3.7包文档(见Github上的代码和ReadTheDocs上的结果):
mytoolbox
|-- mypackage
| |-- __init__.py
| |-- foo.py
| |-- mysubpackage
| |-- __init__.py
| |-- bar.py
|-- doc
| |-- source
| |--index.rst
| |--conf.py
| |-- _templates
| |-- custom-module-template.rst
| |-- custom-class-template.rst
conf.py:
import os
import sys
sys.path.insert(0, os.path.abspath('../..')) # Source code dir relative to this file
extensions = [
'sphinx.ext.autodoc', # Core library for html generation from docstrings
'sphinx.ext.autosummary', # Create neat summary tables
]
autosummary_generate = True # Turn on sphinx.ext.autosummary
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
索引。RST(注意new:recursive: option):
Welcome to My Toolbox
=====================
Some words.
.. autosummary::
:toctree: _autosummary
:template: custom-module-template.rst
:recursive:
mypackage
这足以自动总结包中的每个模块，无论嵌套有多深。对于每个模块，它总结该模块中的每个属性、函数、类和异常。
但奇怪的是，默认的sphinx.ext.autosummary模板不会继续为每个属性、函数、类和异常生成单独的文档页面，也不会从汇总表链接到它们。它可以扩展模板来做到这一点，如下所示，但我不明白为什么这不是默认行为-肯定这是大多数人想要的..?我把它作为一个功能请求。
我必须在本地复制默认模板，然后添加:
复制网站/ sphinx / ext / autosummary /模板/ autosummary /模块。RST到mytoolbox/doc/source/_templates/custom-module-template.rst 复制网站/ sphinx / ext / autosummary /模板/ autosummary /类。RST到mytoolbox/doc/source/_templates/custom-class-template.rst
挂钩到定制模块模板。RST在index中。RST，使用:template:选项。(删除这一行，看看使用默认的site-packages模板会发生什么。)
custom-module-template。RST(右边注明的额外行):
{{ fullname | escape | underline}}
.. automodule:: {{ fullname }}
{% block attributes %}
{% if attributes %}
.. rubric:: Module Attributes
.. autosummary::
:toctree: <-- add this line
{% for item in attributes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block functions %}
{% if functions %}
.. rubric:: {{ _('Functions') }}
.. autosummary::
:toctree: <-- add this line
{% for item in functions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block classes %}
{% if classes %}
.. rubric:: {{ _('Classes') }}
.. autosummary::
:toctree: <-- add this line
:template: custom-class-template.rst <-- add this line
{% for item in classes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block exceptions %}
{% if exceptions %}
.. rubric:: {{ _('Exceptions') }}
.. autosummary::
:toctree: <-- add this line
{% for item in exceptions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block modules %}
{% if modules %}
.. rubric:: Modules
.. autosummary::
:toctree:
:template: custom-module-template.rst <-- add this line
:recursive:
{% for item in modules %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
custom-class-template。RST(右边注明的额外行):
{{ fullname | escape | underline}}
.. currentmodule:: {{ module }}
.. autoclass:: {{ objname }}
:members: <-- add at least this line
:show-inheritance: <-- plus I want to show inheritance...
:inherited-members: <-- ...and inherited members too
{% block methods %}
.. automethod:: __init__
{% if methods %}
.. rubric:: {{ _('Methods') }}
.. autosummary::
{% for item in methods %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block attributes %}
{% if attributes %}
.. rubric:: {{ _('Attributes') }}
.. autosummary::
{% for item in attributes %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
其他回答
从Sphinx 3.1版(2020年6月)开始，Sphinx .ext.autosummary(终于!)具有自动递归。
因此，不再需要硬编码模块名称或依赖第三方库，如Sphinx AutoAPI或Sphinx autopackagsummarmary来进行自动包检测。
示例Python 3.7包文档(见Github上的代码和ReadTheDocs上的结果):
mytoolbox
|-- mypackage
| |-- __init__.py
| |-- foo.py
| |-- mysubpackage
| |-- __init__.py
| |-- bar.py
|-- doc
| |-- source
| |--index.rst
| |--conf.py
| |-- _templates
| |-- custom-module-template.rst
| |-- custom-class-template.rst
conf.py:
import os
import sys
sys.path.insert(0, os.path.abspath('../..')) # Source code dir relative to this file
extensions = [
'sphinx.ext.autodoc', # Core library for html generation from docstrings
'sphinx.ext.autosummary', # Create neat summary tables
]
autosummary_generate = True # Turn on sphinx.ext.autosummary
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
索引。RST(注意new:recursive: option):
Welcome to My Toolbox
=====================
Some words.
.. autosummary::
:toctree: _autosummary
:template: custom-module-template.rst
:recursive:
mypackage
这足以自动总结包中的每个模块，无论嵌套有多深。对于每个模块，它总结该模块中的每个属性、函数、类和异常。
但奇怪的是，默认的sphinx.ext.autosummary模板不会继续为每个属性、函数、类和异常生成单独的文档页面，也不会从汇总表链接到它们。它可以扩展模板来做到这一点，如下所示，但我不明白为什么这不是默认行为-肯定这是大多数人想要的..?我把它作为一个功能请求。
我必须在本地复制默认模板，然后添加:
复制网站/ sphinx / ext / autosummary /模板/ autosummary /模块。RST到mytoolbox/doc/source/_templates/custom-module-template.rst 复制网站/ sphinx / ext / autosummary /模板/ autosummary /类。RST到mytoolbox/doc/source/_templates/custom-class-template.rst
挂钩到定制模块模板。RST在index中。RST，使用:template:选项。(删除这一行，看看使用默认的site-packages模板会发生什么。)
custom-module-template。RST(右边注明的额外行):
{{ fullname | escape | underline}}
.. automodule:: {{ fullname }}
{% block attributes %}
{% if attributes %}
.. rubric:: Module Attributes
.. autosummary::
:toctree: <-- add this line
{% for item in attributes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block functions %}
{% if functions %}
.. rubric:: {{ _('Functions') }}
.. autosummary::
:toctree: <-- add this line
{% for item in functions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block classes %}
{% if classes %}
.. rubric:: {{ _('Classes') }}
.. autosummary::
:toctree: <-- add this line
:template: custom-class-template.rst <-- add this line
{% for item in classes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block exceptions %}
{% if exceptions %}
.. rubric:: {{ _('Exceptions') }}
.. autosummary::
:toctree: <-- add this line
{% for item in exceptions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block modules %}
{% if modules %}
.. rubric:: Modules
.. autosummary::
:toctree:
:template: custom-module-template.rst <-- add this line
:recursive:
{% for item in modules %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
custom-class-template。RST(右边注明的额外行):
{{ fullname | escape | underline}}
.. currentmodule:: {{ module }}
.. autoclass:: {{ objname }}
:members: <-- add at least this line
:show-inheritance: <-- plus I want to show inheritance...
:inherited-members: <-- ...and inherited members too
{% block methods %}
.. automethod:: __init__
{% if methods %}
.. rubric:: {{ _('Methods') }}
.. autosummary::
{% for item in methods %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block attributes %}
{% if attributes %}
.. rubric:: {{ _('Attributes') }}
.. autosummary::
{% for item in attributes %}
~{{ name }}.{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
Sphinx AutoAPI正是这样做的。
也许你要找的是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下面是行不通的)。
你可以看看我写的这个脚本。我想它对你有帮助。
这个脚本解析一个目录树，寻找python模块和包，并创建适当的ReST文件，以使用Sphinx创建代码文档。它还创建了一个模块索引。
更新
该脚本现在作为apidoc作为Sphinx 1.1的一部分。
