如何用Sphinx Napoleon提取Google风格文档字符串至数据结构？

直接用sphinx.ext.napoleon解析（无需生成reST） #

sphinx.ext.napoleon基于sphinxcontrib.napoleon，可以跳过完整Sphinx构建流程，直接调用其解析逻辑获取结构化数据：

1. 安装依赖
   确保安装底层依赖库：

   pip install sphinxcontrib-napoleon
   

2. 编写解析代码
   利用GoogleDocstring类的内部属性提取字段，并用dataclass封装结果：

   from sphinxcontrib.napoleon.docstring import GoogleDocstring
   from dataclasses import dataclass, field
   from typing import Dict
   
   @dataclass
   class DocstringInfo:
       summary: str
       extended_description: str
       params: Dict[str, str] = field(default_factory=dict)
   
   def parse_google_docstring(docstring: str) -> DocstringInfo:
       parsed = GoogleDocstring(docstring)
       
       # 提取摘要
       summary = '\n'.join(parsed._summary).strip()
       
       # 提取扩展描述：跳过摘要和参数块，取中间内容
       extended_lines = []
       param_started = False
       for line in parsed._raw:
           stripped_line = line.strip()
           if stripped_line.startswith(':param'):
               param_started = True
               break
           if not param_started:
               extended_lines.append(line)
       
       extended_description = '\n'.join(extended_lines).strip()
       # 移除摘要重复部分
       if extended_description.startswith(summary):
           extended_description = extended_description[len(summary):].strip()
       
       # 提取参数：参数块格式为(参数名, 类型, 描述列表)
       params = {block[0]: '\n'.join(block[2]).strip() for block in parsed._params}
       
       return DocstringInfo(summary, extended_description, params)
   
   # 测试示例
   sample_doc = '''
   计算两个数的和。
   
   支持整数、浮点数运算，返回输入参数的算术和。
   
   Args:
       a: 第一个加数
       b: 第二个加数
   '''
   
   result = parse_google_docstring(sample_doc)
   print("摘要:", result.summary)
   print("扩展描述:", result.extended_description)
   print("参数:", result.params)
   

3. 说明

   • 直接操作GoogleDocstring的_summary、_raw、_params属性，避开reST转换步骤
   • 用dataclass定义结构，让结果更易读和维护

替代方案：使用docstring-parser库 #

如果觉得操作napoleon内部属性不够稳定，可以用专门的解析库，原生支持Google风格：

1. 安装依赖

   pip install docstring-parser
   

2. 解析代码

   from docstring_parser import parse
   from dataclasses import dataclass, field
   from typing import Dict
   
   @dataclass
   class DocstringInfo:
       summary: str
       extended_description: str
       params: Dict[str, str] = field(default_factory=dict)
   
   def parse_google_docstring(docstring: str) -> DocstringInfo:
       parsed = parse(docstring)
       params = {p.arg_name: p.description.strip() for p in parsed.params if p.description}
       return DocstringInfo(
           parsed.short_description or '',
           parsed.long_description or '',
           params
       )
   
   # 测试示例
   sample_doc = '''
   计算两个数的和。
   
   支持整数、浮点数运算，返回输入参数的算术和。
   
   Args:
       a: 第一个加数
       b: 第二个加数
   '''
   
   result = parse_google_docstring(sample_doc)
   print("摘要:", result.summary)
   print("扩展描述:", result.extended_description)
   print("参数:", result.params)
   

这个库API更稳定，无需依赖Sphinx生态，适合单独做文档字符串解析。

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