Python: 使用sphinx生成python项目文档

前言

本篇记录使用sphinx生产成python项目文档的方法。

安装sphinx

直接通过pip安装sphinx：

pip install sphinx

生成配置文件

进入项目根目录，创建doc文件夹，生成配置文件：

mkdir doc
cd doc
sphinx-quickstart

出现以下提示：

Separate source and build directories (y/n) [n]: y
Project name: 
Author name(s): 
Project version []: 
Project language [en]: 

修改配置文件

安装sphinx主题美化文档：

pip install sphinx_rtd_theme

修改doc/source/conf.py文件：

import os
import sys
# 添加源码路径
sys.path.append(os.path.join(os.path.abspath(__file__), '../../')

# 添加sphinx自动生成脚本
extensions = ['sphinx.ext.autodoc']

# 更改sphinx主题（美观一些）
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

生成rst文件

根据配置文件与源码，生成rst文件：

sphinx-apidoc -o source ../

编译文档

通过rst文件和makefile文件，生成文档：

make html

然后在doc/build下有几个.html文件，打开index.html就能看到文档整体了。