如何配置Sphinx的autodoc仅导入带有docstring的类和函数
解决方案
方案1:使用autodoc内置参数(优先选择)
Sphinx autodoc 默认不带参数的:members:指令本就仅会导出带docstring的成员,如果你当前所有类都被列出,可通过以下两种方式调整:
- 全局调整:打开项目Sphinx配置文件
conf.py,找到autodoc_default_options配置项,删除其中的'undoc-members': True配置。 - 单模块调整:直接在对应rst文件的指令中添加
:no-undoc-members参数,覆盖全局配置,配置示例如下:
.. automodule:: blog.models :members: :no-undoc-members:
配置完成后不需要手动罗列类名,构建时会自动筛选出带docstring的成员展示。
方案2:自定义过滤规则(适配SQLAlchemy等特殊场景)
如果你使用的是SQLAlchemy模型类,存在大量框架自动注入的无docstring内置属性,内置参数无法完全过滤时,可以在conf.py中添加自定义过滤钩子,实现更灵活的筛选:
def skip_member_handler(app, what, name, obj, skip, options): if skip: return True # 跳过无docstring的成员 if not getattr(obj, '__doc__', None): return True # 可按需添加额外过滤规则,比如跳过SQLAlchemy自动生成的属性 if name in ['metadata', 'query', '__tablename__', '__table__']: return True return False def setup(app): app.connect('autodoc-skip-member', skip_member_handler)
添加后重启构建流程即可自动生效。
内容的提问来源于stack exchange,提问作者Tomas Am
相关产品推荐
相关产品推荐

