sphinx快速生成Python API文档
Python有个自带的工具可以生成Python的项目文档叫pydoc,但是我觉得最好用的还是Python-Sphinx,这里我们就讲一下python-Sphinx的使用。
Sphinx可以自动获取代码中的(''' ''' 注释),自动生成文档。
先看看最后要成为的效果,先提起你的兴趣

安装Sphinx
pip install Sphinx
写个我们需要生成文档的项目-代码
建一个测试项目code, 下面有两个Python文件test1.p y和test2.py
(venv) allenwoo@~/renren$ ls code venv (venv) allenwoo@~/renren$ ls code/ test1.py test2.py
test1.py代码:
# -*-coding:utf-8-*- class Test1(): ''' 我是测试类,负责测试 ''' def hello(self): ''' 负责打印Hello, 人人可以学Python :return: ''' print("人人可以学Python") def renren(self): ''' 测试Sphinx自动生成文档 :return: ''' print("自动生成文档") class Test2(): def test_2(self): ''' 我也不知道写什么好,反正我们这里是用来写文档的 :return: ''' print("文档自动生成测试2") def renren_2(self): ''' 所以我们开发的时候就应该在这里写好文档,然后用Sphinx自动生成 :return: ''' print("自动生成文档2")
test2.py代码:
# -*-coding:utf-8-*- def init_test(): ''' 用于初始化项目测试,不需要任何参数 :return: ''' print("初始化项目") def start(): ''' 启动项目入口, :return: ''' test(3) def test(v): ''' 项目运行主要函数,需要传入一个参数\n v:<int> :return: ''' print(v)
使用Python-Sphinx doc
1. 选择配置
除了以下项目外,其他的我都使用了默认值:
(venv) allenwoo@~/renren/doc$ sphinx-quickstart Welcome to the Sphinx 1.5.5 quickstart utility. Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets). Enter the root path for documentation. > Root path for the documentation [.]: . > Separate source and build directories (y/n) [n]: y > Project name: Code Pro > Author name(s): Allen Woo > Project version []: 1.0 > Project language [en]: zh_cn > autodoc: automatically insert docstrings from modules (y/n) [n]: y > doctest: automatically test code snippets in doctest blocks (y/n) [n]: y > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y > coverage: checks for documentation coverage (y/n) [n]: y > viewcode: include links to the source code of documented Python objects (y/n) [n]: y
2.配置conf.py
在source/conf.py文件中加入如下代码, 导入自己的项目路径
import os import sys sys.path.insert(0, os.path.abspath('./../../code'))
3. 生成rst文件
注意:-o 后面跟的是保存rst文件的路径, 你的index.rst在哪个目录,那你就指定哪个目录。然后在后面的是你的项目(代码)路径
(venv) allenwoo@~/renren/doc$ sphinx-apidoc -o ./source ../code/ Creating file ./test1.rst. Creating file ./test2.rst. Creating file ./modules.rst.
4. 最后执行make html,生成html文件
(venv) allenwoo@~/renren/doc$ make html Running Sphinx v1.5.5 loading translations [zh_cn]... done loading pickled environment... done building [mo]: targets for 0 po files that are out of date building [html]: targets for 0 source files that are out of date updating environment: 0 added, 0 changed, 0 removed looking for now-outdated files... none found no targets are out of date. build succeeded. Build finished. The HTML pages are in build/html.
OK!
5.现在我们用浏览器打开doc/build/html/index.html,如下:
如果你也和我一样觉得页面UI很丑,那就继续看下一步,我们安装一个theme(主题)
主页面:

文档页面:

源码页面:

安装Sphinx主题
python sphinx的主体包邮很多,我最喜欢 readthedocs风格的:
这种风格的sphinx主体包叫sphinx_rtd_theme
可以下载安装,也可以命令安装。
命令安装:
pip install sphinx_rtd_theme
下载地址:
https://github.com/rtfd/sphinx_rtd_theme
注意:下载安装的配置和使用命令安装的不一样,具体可以看GIthub上的文档:
配置:
编辑我们的source/conf.py
导入模块:
import sphinx_rtd_theme
将 html_theme = "alabaster"改成如下,在加上html_theme_path
html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
最后我们再执行一次:make html
然后再访问文档,发现里面变的好看了,是不是?

作者:HiWoo
链接:https://www.jianshu.com/p/d4a1347f467b
【推荐】国内首个AI IDE,深度理解中文开发场景,立即下载体验Trae
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 从 HTTP 原因短语缺失研究 HTTP/2 和 HTTP/3 的设计差异
· AI与.NET技术实操系列:向量存储与相似性搜索在 .NET 中的实现
· 基于Microsoft.Extensions.AI核心库实现RAG应用
· Linux系列:如何用heaptrack跟踪.NET程序的非托管内存泄露
· 开发者必知的日志记录最佳实践
· TypeScript + Deepseek 打造卜卦网站:技术与玄学的结合
· Manus的开源复刻OpenManus初探
· AI 智能体引爆开源社区「GitHub 热点速览」
· 三行代码完成国际化适配,妙~啊~
· .NET Core 中如何实现缓存的预热?
2019-02-10 Linux学习之用户管理命令与用户组管理命令(十五)
2019-02-10 Linux学习之用户配置文件详解(十四)
2019-02-10 Linux学习之Vim/Vi使用(十三)