python生成api文档_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-*-

classTest1():'''我是测试类，负责测试'''

defhello(self):'''负责打印Hello， 人人可以学Python

:return:'''

print("人人可以学Python")defrenren(self):'''测试Sphinx自动生成文档

:return:'''

print("自动生成文档")classTest2():deftest_2(self):'''我也不知道写什么好，反正我们这里是用来写文档的

:return:'''

print("文档自动生成测试2")defrenren_2(self):'''所以我们开发的时候就应该在这里写好文档，然后用Sphinx自动生成

:return:'''

print("自动生成文档2")

test2.py代码：

#-*-coding:utf-8-*-

definit_test():'''用于初始化项目测试，不需要任何参数

:return:'''

print("初始化项目")defstart():'''启动项目入口，

:return:'''test(3)deftest(v):'''项目运行主要函数，需要传入一个参数\n

v:

:return:'''

print(v)

使用Python-Sphinx doc

1. 选择配置

除了以下项目外，其他的我都使用了默认值：

(venv) allenwoo@~/renren/doc$ sphinx-quickstart

Welcome to the Sphinx1.5.5quickstart utility.

Please enter valuesforthe following settings (just press Enter to

accept a default value,if one is given inbrackets).

Enter the root pathfordocumentation.> Root path forthe 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文件中加入如下代码， 导入自己的项目路径

importosimportsys

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.5loading translations [zh_cn]... done

loading pickled environment... done

building [mo]: targetsfor0 po files that are out of date

building [html]: targetsfor0 source files that are out of date

updating environment: 0 added, 0 changed, 0 removed

lookingfor now-outdated files... none found

no targets are out of date.

build succeeded.

Build finished. The HTML pages arein build/html.

OK！

5.现在我们用浏览器打开doc/build/html/index.html,如下：

如果你也和我一样觉得页面UI很丑，那就继续看下一步，我们安装一个theme(主题)

主页面：

文档页面：

源码页面：

安装Sphinx主题

python sphinx的主体包邮很多，我最喜欢 readthedocs风格的：

这种风格的sphinx主体包叫sphinx_rtd_theme

可以下载安装，也可以命令安装。

命令安装：

pip install sphinx_rtd_theme

下载地址：

配置：

编辑我们的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

然后再访问文档，发现里面变的好看了，是不是？