Sphinx为何将我的函数文档字符串参数格式化为单行？

Hey there! As a fellow Sphinx user who's been through this exact hiccup, let me break down what's going on and how to fix it.

The Root Cause #

The issue boils down to how Sphinx parses your docstring format by default:

• You’re using reStructuredText-style parameter tags (the :param ...: syntax), but your current docstring doesn’t give Sphinx clear hints to split parameter descriptions into separate lines. By default, Sphinx treats the text immediately following the :param: tag as a single continuous line unless you structure it differently.
• If you haven’t enabled extensions that handle richer docstring styles, Sphinx will stick to its basic parsing rules for reStructuredText.

Fixes to Try #

1. Adjust Your ReStructuredText Docstring Format

If you want to keep using the :param: syntax, tweak your docstring to add line breaks and indentation for parameter descriptions. This tells Sphinx to render each parameter’s details on its own line:

def arima_rolling_forecast(training_set, testing_set, order, solver='lbfgs'):
    """ 基于给定的训练集和测试集运行ARIMA滚动预测。
    
    :param pandas.Series training_set: 
        用于模型训练的时间序列训练集数据。
    :param pandas.Series testing_set: 
        用于验证模型预测效果的测试集数据。
    :param collections.namedtuple order: 
        ARIMA模型的阶数参数，格式为(p, d, q)。
    :param string solver: 
        模型训练时使用的求解器，默认值为'lbfgs'。
    """

The indentation after the :param: tag signals to Sphinx that the following text belongs to the parameter’s description, and it will render it below the parameter name instead of squishing everything into one line.

2. Use Google-Style Docstrings with the Napoleon Extension

If you prefer a more readable, human-friendly docstring format, enable Sphinx’s napoleon extension (which supports Google-style docstrings). Here’s how:

1. Open your Sphinx conf.py file and add 'sphinx.ext.napoleon' to the extensions list:

   extensions = [
       'sphinx.ext.autodoc',
       'sphinx.ext.napoleon',  # Add this line
   ]
   

2. Rewrite your docstring to use Google-style syntax:

   def arima_rolling_forecast(training_set, testing_set, order, solver='lbfgs'):
       """ 基于给定的训练集和测试集运行ARIMA滚动预测。
       
       Args:
           training_set (pandas.Series): 训练集。
           testing_set (pandas.Series): 测试集。
           order (collections.namedtuple): ARIMA阶数(p, d, q)。
           solver (string): 使用的求解器，默认值为'lbfgs'。
       """
   

Napoleon will parse this into a clean, multi-line parameter list in your final Sphinx documentation.

3. Double-Check Autodoc Settings (If Needed)

If you still see single-line rendering, check your conf.py for settings that might force line wrapping. For example, ensure autodoc_wrap_signature is set to True if you want long parameter signatures to wrap (though this mostly affects function signatures rather than docstring parameters).

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