使用Sphinx生成Python包文档：两大技术疑问求助

Great questions! Let's walk through solutions to both of your issues with Sphinx's autosummary:

You don't have to list each module one by one—there are two reliable ways to automate this:

Use the :recursive: flag #

This is the simplest approach for packages with nested modules. Add the :recursive: option to your autosummary block, then just specify the top-level package. Sphinx will automatically traverse all submodules and generate summaries for them:

package_1
---------
.. autosummary::
   :toctree: _generated
   :recursive:

   package_1

Just make sure your conf.py still has autosummary_generate = True enabled, and that Sphinx can properly discover all your package modules (double-check sys.path includes your project root if needed).

Use wildcard patterns #

If you only want to target a subset of modules (e.g., all modules starting with module_), you can use wildcard syntax:

package_1
---------
.. autosummary::
   :toctree: _generated

   package_1.module_*

Note that wildcard support depends on your Sphinx version—most modern versions (>=3.0) handle this smoothly, but if you're on an older release, you might need to ensure autosummary_generate_overview is set appropriately in conf.py.

Autosummary's detail pages are powered by Sphinx's autodoc under the hood, so you can control their appearance through a mix of autosummary-specific options and autodoc configuration:

Use autosummary block options #

Add these directly to your autosummary directive to tweak output:

• :nosignatures:: Hides function/method signatures on the summary page (and propagates to the detail page if using default templates)
• :template:: Points to a custom template file to fully customize the detail page structure (more on this below)
• :toctree:: You're already using this, but it controls where the generated detail pages are stored

Example with options:

.. autosummary::
   :toctree: _generated
   :nosignatures:

   package_1.module_1

Tweak autodoc settings in conf.py #

Since autosummary uses autodoc to render detail pages, adjusting autodoc's global settings will affect how those pages look. Add these to your conf.py:

# Control member visibility and order
autodoc_default_options = {
    'members': True,  # Show all members
    'undoc-members': True,  # Include members without docstrings
    'show-inheritance': True,  # Display inheritance hierarchy
    'member-order': 'bysource'  # Keep members in the order they appear in code
}

# Optional: Disable type hints if you don't want them displayed
autodoc_typehints = 'none'

Customize templates for full control #

If you need to completely overhaul the detail page layout, create a custom template:

1. Copy the default autosummary module template from your Sphinx installation (usually located at sphinx/templates/autosummary/module.rst) into your project's _templates/autosummary/ directory
2. Modify the copied template to adjust sections, add custom text, or reorder content
3. Reference it in your autosummary block with the :template: option:

.. autosummary::
   :toctree: _generated
   :template: autosummary/module.rst  # Path relative to _templates

   package_1.module_1

内容的提问来源于stack exchange，提问作者10-Mar