Sphinx 自动构建文档

# =================================================
# Author  : Mikigo
# Time    : 2022/5/5
# version ：1.0
# =================================================

Sphinx 是一个文档工具，它可以轻松的撰写出清晰且优美的文档，非常多优秀的开源项目都使用 Sqhinx 构建其官方文档，比如著名的 Reqeusts、 Django、 Pytest 等等，甚至 Python 的官方文档也是用它构建的，要知道 Sqhinx 本身也是用 Python 写的，所以 Sphinx 已成为 Python 项目首选的文档工具，据说它还支持其他语言的比如C++，我没试过，不知道效果如何，有兴趣的可以试试。

一、构建步骤

1、安装依赖:

requirements.txt

sphinx
sphinx-press-theme
recommonmark
sphinx-markdown-tables
jieba

pip3 install -r requirements.txt

依赖不多，其实只需要按照一个最基础的 sphinx 就行了，其他就是一些主题包，我们就选了一个简单而不失优雅的主题，所以也安装一下。

2、新建文档项目

如果你要建一个新的文档项目，那你只需要在任意一个目录下，使用：

sphinx-quickstart

然后按照提示输入项目名称、作者、版本号就行了。

细心的伙伴可能注意过 Pycharm 里面提供了这个功能，Tools —> Sphinx Quickstart，但是我不推荐使用这个哈，因为它默认是在根目录下新建，而一般我们都会放到一个 doc 目录下，所以你需要在设置里面去目录切换，挺麻烦的。

3、给各模块生成 API 文件

sphinx-apidoc -o source ../../

注意最后的路径，如果是多个目录模块可以重复执行命名，指定不同的模块就好了。

4、构建 html 文档

make html

二、注释模板

1、文件注释头模板

#!/usr/bin/env python3
# _*_ coding:utf-8 _*_
"""
:Author:youname@uniontech.com
:Date  :${DATE} ${TIME}
"""

Pycharm 提供文件注释头模板功能：

• File —> Settings —> Editor —> File and Code Templates —> Python Script
• 在右侧输入框里面将上面模板粘贴进去，再点 OK 就行了。

这样在新建 py 文件的时候就会自动生成文件注释头。

2、函数功能注释模板

举例

"""
 测试机环境安装 （注意前面空一格）
:param user: 用户名
:param ip: 测试机IP
:param password: 测试机密码
:return:
"""

如果是多行注释，行与行之间需要空一行，这样在html中展示才会有换行的效果。

Pycharm 提供函数功能注释模板功能：

• File —> Settings —> Tools —> Python Integrated Tools —> Docstrings

• 在 Docstring format 下拉框里面选择 reStructuredText，再点 OK 就行了。

这样在函数名下面只需要输入三对双引号，然后直接回车，就可以自动把以上模板带出来，非常方便。

三、自动化每日构建

文档持续构建，实现及时更新。

使用 Jenkins 流水线任务每日自动拉取 git 代码，自动构建最新的 html 文档，并自动发布到 web 服务器。