python sphinx-autodoc
## 关于Sphinx的autodoc，这里有些你可能没注意到的细节
接手过几个遗留的Python项目，最让人头疼的往往不是代码有多烂，而是文档和代码完全对不上。文档里写的参数名在代码里根本不存在，或者模块明明已经重写了三版，文档还停留在第一版。这时候就会特别想念自动生成文档的工具，而Sphinx autodoc就是其中绕不开的一个选择。
它到底是什么？
Sphinx autodoc严格来说不算一个独立的工具，它是Sphinx文档生成器的一个扩展插件。Sphinx自己的强项是处理rst或者MyST格式的文档文件，但autodoc解决了另一个痛点——直接从Python源码里提取文档字符串（docstring）转换成文档页面。
可以把这个过程想象成装修房子。Sphinx是施工队，它能按照设计图纸（rst文件）搭建整个房子。而autodoc就像是一个自动化的量尺，它直接从代码墙上读取标注（docstring），然后告诉施工队该在哪里贴标签、写说明。这样做的好处很明显——代码改动了docstring，文档自然跟着更新，从根本上杜绝了“两个人各说各话”的情况。
它能做什么，做到什么程度？
autodoc最基础的功能是扫描Python模块、类、函数、方法的docstring，把它们变成结构化的文档。但深入用下去会发现它其实有一些挺实用的细节：
自动推导类型：如果函数写了类型注解，比如
def process(name: str) -> list:，autodoc会自动把类型信息展示出来，不用在docstring里重复写类型。这比纯依赖docstring文本更可靠，因为类型注解是代码的一部分，更容易保持同步。控制文档展示的颗粒度：可以用
autoclass、autofunction这些指令独立控制每个元素的展示方式。比如想展示类的所有静态方法但隐藏私有方法，可以在配置里指定exclude-members。模块级的文档：不仅仅能生成类和函数的文档，还能提取模块的
__doc__作为模块说明，这对于组织大型项目特别有用。和Sphinx其他扩展配合：比如配合
napoleon扩展可以解析Google风格的docstring，配合viewcode可以直接跳转到源代码。这些配合在实战中往往比单独用autodoc顺手得多。
怎么用起来？
最基本的用法其实挺简单的。首先确保安装了sphinx和sphinx-autodoc（有时候带着sphinx.autodoc其实是Sphinx自带的，但旧版本可能需要单独装）：
pip install sphinx sphinx-rtd-theme在Sphinx的conf.py里加上扩展：
extensions=['sphinx.ext.autodoc',# 其他扩展...]然后在rst文件里使用指令：
.. automodule:: my_project.core :members: :undoc-members: :show-inheritance: .. autoclass:: my_project.core.DataProcessor :members: :private-members:这里面:members:表示展示所有公共成员，:undoc-members:连没有docstring的也展示出来（有时候参数和函数签名本身就足够说明问题，这在工具脚本里很实用），:show-inheritance:显示继承关系。
一个常见的坑是：autodoc需要导入模块来读取docstring，所以如果项目里有在模块顶层执行的文件操作或数据库连接，运行Sphinx构建就会报错。解决办法是在conf.py里设置autodoc_mock_imports，把那些没什么实际意义的第三方库mock掉。
最佳实践
用的时间长了，摸索出几个比较实用的做法：
docstring的写法直接决定输出质量。autodoc能把docstring原样搬到文档里，所以写docstring时要想着“这段文字会在文档里出现”，而不仅仅是给开发者看。多写些使用场景和边界条件，少写那些“这个函数做什么”的重复废话。比如：
defcalculate_discount(price:float,rate:float=0.1)->float:""" 计算商品折后价格。 参数 price 应大于零，rate 应在 0 到 1 之间。如果 rate 为 0.15， 表示打 8.5 折。返回结果保留两位小数。 :param price: 原价 :param rate: 折扣率，默认 0.1（9折） :return: 折后价格 """利用好autodoc_default_options。在conf.py里设置一次，就不用每个rst文件都重复写选项：
autodoc_default_options={'members':True,'member-order':'bysource','special-members':'__init__','undoc-members':True,'exclude-members':'__weakref__'}分模块组织文档。不要试图用一个rst文件塞下整个项目，建议一个模块对应一个rst文件，然后用toctree串起来。这样维护时清晰，构建时间也能接受。
配合类型注解。autodoc对Python 3.5+的类型注解支持良好，建议多用。比如用Optional[str]而不是Union[str, None]能更直观，autodoc也能正确渲染。
和同类技术对比
市面上能做类似事情的工具其实不多，主要是pydoc和MkDocs。简单对比一下各自的特点：
和标准库pydoc比较
pydoc是Python自带的，用python -m pydoc -p 8080就能开一个简单的HTTP服务查看文档。优点是零依赖，但功能实在太简陋。它只能展示当前源码里的信息，没法加额外的说明文字。而且生成的文档没法定制主题，看起来永远是那个朴素的HTML风格。如果文档需求只是给自己快速查一查，pydoc够用。但要是给用户或团队成员看，还是得用Sphinx autodoc。
和MkDocs比较
MkDocs是用Markdown写文档，配合mkdocstrings插件也能提取docstring。MkDocs的优势是上手特别快，不需要学rst语法，对习惯Markdown的开发者很友好。但MkDocstrings在提取复杂类型信息时不如Sphinx autodoc准确，特别是涉及到泛型、多态的情况。Sphinx在这方面根基更稳，因为它本身就是为Python设计的，对Python类型系统的理解更深。
一个现实的选择
小型工具库或者内部项目，用MkDocs+mkdocstrings就挺好，每天写文档压力小。但一旦项目大了，需要细粒度控制文档结构（比如把文档切分成教程、API参考、设计说明等不同章节），或者要生成PDF版本，Sphinx autodoc的优势就体现出来了。它虽然学习曲线比MkDocs陡一点，但后期扩展性和灵活性更强。
记得有个朋友维护着一个中等规模的Python库，文档一直用Sphinx autodoc生成。有次他们重构了部分API，改完代码后跑一遍Sphinx build，文档自动更新了所有函数签名和参数说明，只花几分钟。而另一个用纯手工写文档的项目，一个参数名修改可能要翻遍几十个文件。这种差异在维护阶段慢慢会放大很多倍。