sphinx快速生成Python API文档

Posted -零

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了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-*-
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")
    def renren_2(self):
        ‘‘‘
        所以我们开发的时候就应该在这里写好文档,然后用Sphinx自动生成

        :return: 
        ‘‘‘
        print("自动生成文档2")

test2.py代码:

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

def init_test():
    ‘‘‘
    用于初始化项目测试,不需要任何参数
    :return: 
    ‘‘‘
    print("初始化项目")


def start():
    ‘‘‘
    启动项目入口,
    :return: 
    ‘‘‘
    test(3)

def test(v):
    ‘‘‘
    项目运行主要函数,需要传入一个参数

    v:<int>
    :return: 
    ‘‘‘

    print(v)

使用Python-Sphinx doc

1. 选择配置
除了以下项目外,其他的我都使用了默认值:

(venv) allenwoo@~/renren/doc$ sphinx-quickstart 
Welcome to the Sphinx 1.5.5 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

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

import os
import sys
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.5
loading translations [zh_cn]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

Build finished. The HTML pages are in build/html.

OK!

5.现在我们用浏览器打开doc/build/html/index.html,如下:
如果你也和我一样觉得页面UI很丑,那就继续看下一步,我们安装一个theme(主题)

主页面:


 
技术图片
 

文档页面:

技术图片

源码页面:

技术图片
 

安装Sphinx主题
python sphinx的主体包邮很多,我最喜欢 readthedocs风格的:
这种风格的sphinx主体包叫sphinx_rtd_theme

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

命令安装:

pip install sphinx_rtd_theme

下载地址:

https://github.com/rtfd/sphinx_rtd_theme
注意:下载安装的配置和使用命令安装的不一样,具体可以看GIthub上的文档:

配置:
编辑我们的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
然后再访问文档,发现里面变的好看了,是不是?

技术图片
 

作者:HiWoo
链接:https://www.jianshu.com/p/d4a1347f467b

以上是关于sphinx快速生成Python API文档的主要内容,如果未能解决你的问题,请参考以下文章

利用sphinx为python项目生成API文档

python代码docstring生成文档之sphinx

Python 程序有啥好的自动从注释生成文档的方法

如何使用 Sphinx 为 Python 属性设置器生成文档?

sphinx:python项目文档自动生成

最终用户将如何访问 Sphinx 为 Python 包生成的文档?