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

最新推荐文章于 2024-08-29 12:24:50 发布

weixin_34220963

最新推荐文章于 2024-08-29 12:24:50 发布

阅读量171

点赞数

文章标签： python

原文链接：https://my.oschina.net/ranvane/blog/2251175

版权

2019独角兽企业重金招聘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.

转载于:https://my.oschina.net/ranvane/blog/2251175