sphinx python mysql_不求甚解的使用sphinx生成Python文档

这里我们就不求甚解的讲一下python-Sphinx的使用，目的是使用，不是为了详细了解。

先看一下结果：

Sphinx可以自动获取代码中的(''' ''' 注释)，自动生成文档。

安装Sphinx

pip install Sphinx

然后准备一个写好'''   ''' 注释的python文件test1.py：

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")

开始使用sphinx生成Python文档：

命令：

sphinx-quickstart

1、配置中我认为需要注意的地方：

a、 Separate source and build directories  #单独的源和构建目录  默认为n，

b、autodoc: automatically insert docstrings from modules (y/n) [n]: # 自动从模块插入文档字符串  默认为n，我选择y

c、intersphinx: link between Sphinx documentation of different projects #不同项目的Sphinx文档之间的链接 这个看需要

其余的我选择默认选项。

2、修改conf.py文件

需要修改加入源代码目录，不然生成失败。

因为我是在源代码文件夹下的source目录操作，所以加入以下代码：

import os

import sys

sys.path.insert(0, os.path.abspath('./../'))

3、生成文档的源文件

命令是

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

这个命令后面的参数有两个：

a、第一个参数是你运行sphinx-quickstart 配置好文档项目后，会生成一个index.rst文件的路径目录，因为我选择了‘单独的源和构建目录’选项，所以我的代码目录里有个source文件夹，这里我的第一个参数就是 ：

./source

b、第二个参数：

你的项目(代码)路径，所以我的第二个参数就是：

./

那么我的命令就是：

sphinx-apidoc -o ./source ./

#输出

Creating file ./source\test.rst.

Creating file ./source\modules.rst.

4、最后使用 make html命令生成文档：

生成的文件在build\html里面。

#make html 的输出内容：

Running Sphinx v1.8.1

loading translations [zh_CN]... done

making output directory...

building [mo]: targets for 0 po files that are out of date

building [html]: targets for 1 source files that are out of date

updating environment: 1 added, 0 changed, 0 removed

reading sources... [100%] index

looking for now-outdated files... none found

pickling environment... done

checking consistency... done

preparing documents... done

Building prefix dict from the default dictionary ...

Dumping model to file cache C:\Users\ADMINI~1\AppData\Local\Temp\jieba.cache

Loading model cost 0.739 seconds.

Prefix dict has been built succesfully.

generating indices... genindex

writing additional pages... search

copying static files... done

copying extra files... done

dumping search index in Chinese (code: zh) ... done

dumping object inventory... done

build succeeded.

The HTML pages are in build\html.