如何用Sphinx抓取分析脚本文件中的Docstrings？

Absolutely, you can get Sphinx to pick up the docstrings from your standalone scripts—you just need to treat them as importable modules and tweak a few settings. Here's how to do it step by step:

1. Make Your Scripts Sphinx-Friendly #

First, ensure your scripts are safe for Sphinx to import (since Sphinx needs to load the module to extract docstrings):

• Add a __name__ guard: Wrap all code that runs when you execute the script directly in if __name__ == '__main__':. This prevents the code from running when Sphinx imports the script as a module, avoiding errors or unwanted behavior.
• Keep the top-level docstring: The first triple-quoted string in your script is the module docstring—this is what Sphinx will prioritize for documentation.

Example script structure:

"""
Specific Analytical Question 1
------------------------------
Uses MyModule to load and analyze dataset X, outputting summary statistics 
for the key variable Y. Designed to run interactively in Spyder for variable inspection.
"""
import MyModule

# Define variables or helper code here (non-execution logic)
dataset_path = "../data/dataset_x.csv"

if __name__ == '__main__':
    # Code that runs only when executing the script directly
    data = MyModule.load_data(dataset_path)
    summary = MyModule.calculate_summary(data, "Y")
    print(summary)

2. Update Sphinx's conf.py to Find Your Scripts #

Sphinx needs to know where your Scripts_using_MyModule folder is to import the scripts. Add this to your conf.py (adjust the path based on your docs folder structure):

import os
import sys
# If your docs are in a `docs` folder inside MyProject, use this path:
sys.path.insert(0, os.path.abspath('../../Scripts_using_MyModule'))
# If docs are at the same level as MyModule/Scripts, use: sys.path.insert(0, os.path.abspath('../Scripts_using_MyModule'))

3. Document the Scripts in Your RST Files #

Choose an option based on how many scripts you have:

Option A: Manual Entry (For a Small Number of Scripts) #

In your main documentation RST file (e.g., index.rst), add sections for each script using the automodule directive. Since your scripts don't have functions/classes, this will display the top-level docstring:

## Analytical Scripts

### Specific Analytical Question 1
.. automodule:: Specific_Analytical_Question_1
   :noindex:  # Optional: prevents cluttering the search index

### Specific Analytical Question 2
.. automodule:: Specific_Analytical_Question_2
   :noindex:

Option B: Automate with sphinx-apidoc (For Many Scripts) #

If you have lots of scripts, use sphinx-apidoc to generate RST files automatically. Run this command from your docs directory:

sphinx-apidoc -o source/ ../Scripts_using_MyModule

This creates a separate RST file for each script in your docs source folder. Include these files in your main index.rst using a toctree:

## Analytical Scripts
.. toctree::
   :maxdepth: 2
   :caption: Scripts:

   Specific_Analytical_Question_1
   Specific_Analytical_Question_2

Key Notes #

• Never skip the __name__ guard: Without it, Sphinx will run all top-level code when importing the script, which can cause errors (e.g., file not found exceptions, long-running computations).
• Refine module docstrings: Since your scripts don't have functions, the top-level docstring is the main content Sphinx will display—make sure it clearly explains the script's purpose, inputs, and expected outputs.

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