Sphinx中非模块Python脚本自动生成文档的方法咨询

Absolutely, this is exactly what Sphinx's built-in autodoc extension is designed for—you don’t need extra tools like sphinx-gallery or autoprogram for this core docstring extraction task. It’s purpose-built to pull module-level docstrings, function docstrings, class docstrings, and more directly from your Python scripts and turn them into clean Sphinx documentation, just like the directives you mentioned.

Here’s a step-by-step breakdown to make this work for your specific script:

1. Enable the Autodoc Extension #

First, make sure sphinx.ext.autodoc is enabled in your Sphinx project’s conf.py:

extensions = [
    # ... keep any other extensions you’re using
    'sphinx.ext.autodoc',
]

2. Tell Sphinx Where to Find Your Script #

If your target Python script is a standalone file (not part of a formal package), you need to add its directory to Sphinx’s import path in conf.py:

import os
import sys
# Replace '../path/to/your/scripts' with the actual relative path to your script's folder
sys.path.insert(0, os.path.abspath('../path/to/your/scripts'))

3. Use Autodoc Directives in Your .rst Files #

Now you can use autodoc’s directives to pull docstrings directly into your documentation:

Example 1: Extract Entire Script Content #

If your script is named my_script.py, add this to your .rst file to pull the module’s top-level docstring plus all functions/classes and their internal docstrings:

.. automodule:: my_script
    :members:
    :undoc-members:  # Optional: include members without docstrings
    :private-members:  # Optional: include private members (like _helper_func)

Example 2: Extract a Specific Function Only #

If you only want documentation for one function (e.g., calculate_total in my_script.py), use:

.. autofunction:: my_script.calculate_total

4. Build Your Documentation #

Run the standard Sphinx build command to generate the final HTML (or other format) docs:

sphinx-build -b html docs/source docs/build

Quick Note on Your Previous Tools #

• sphinx-gallery is focused on creating interactive example galleries with code outputs, not just extracting static docstrings.
• sphinxcontrib.autoprogram is built for generating docs for argparse command-line interfaces, not general script docstrings.

Autodoc is the lightweight, direct solution you’re looking for—it’s fully integrated with Sphinx and does exactly what you need: auto-generate docs from both module-level and function-level docstrings in your scripts.

内容的提问来源于stack exchange，提问作者Nico Albers