使用sphinx自动提取python中的注释成为接口文档

写好了代码,交付给他人使用的时候,查看代码固然可以了解各类和函数的功能细节,但接口文档能更方便的查找和说明功能。所以,一价与代码同步的接口文档是很有必要的。sphinx可以根据python中的注释,自动的生成接口文档,这样有利于保证文档和代码功能的同步。让我们来了解如何自动生成文档。

复制代码
class A:
    '''
    你好!
    '''
    @staticmethod
    def Aa():
        '''
        你也好!
        '''
        fun1()

看到类和函数中,都加入了注释。

  1. 安装shpinx

    pip install sphinx -i https://pypi.doubanio.com/simple --trusted-host pypi.doubanio.com

使用国内的镜像安装比较快。

  1. 配置shpinx

    cd myproject sphinx-quickstart
    Enter the root path for documentation.

    Root path for the documentation [.]: doc
    Project name: XXX
    Author name(s): XXX
    Project version []: 1.0
    Project release [1.0]:
    Project language [en]: zh_CN #如果注释中有中文,这里必须设置。否则生成接口文档出错。
    autodoc: automatically insert docstrings from modules (y/n) [n]: y
    其它项都选择默认

完成之后,会在当前目录创建 doc 目录,所有sphinx相关的文件都在 doc目录下。

复制代码
$ ls doc/
_build  conf.py  index.rst  Makefile  _static  _templates
$ vi doc/conf.py  #修改文件内容
sys.path.insert(0, os.path.abspath('.')) 
sys.path.insert(0, os.path.abspath('..')) # 缺少此行会导致在make html时提示 __import__出错,找不到module。 所以必须把上一级目录(即代码所在目录)include进来

$ sphinx-apidoc -o doc/ .
Creating file doc/a.rst.
Creating file doc/modules.rst

# 把生成的 doc/modules.rst添加到index.rst
$ vi doc/index.rst

Contents:
 .. toctree::
    :maxdepth: 2

    modules.rst

生成html页面
$ cd doc
$ make html

生成的html文档,在doc/_build/html里。

sphinx对仅工作在python2.7 或python3上。当文件中有中文时,可能会报错:'ascii' codec can't decode byte 0xe2 in position xxx。可以在报错的地方加入:

复制代码
import sys
reload(sys)
sys.setdefaultencoding('utf-8')
相关推荐
青衫客363 分钟前
基于 Python 构建的安全 gRPC 服务——TLS、mTLS 与 Casbin 授权实战
python·安全·微服务
-dzk-1 小时前
【3DGS复现】Autodl服务器复现3DGS《简单快速》《一次成功》《新手练习复现必备》
运维·服务器·python·计算机视觉·3d·三维重建·三维
楼田莉子2 小时前
Qt开发学习——QtCreator深度介绍/程序运行/开发规范/对象树
开发语言·前端·c++·qt·学习
摩羯座-185690305942 小时前
爬坑 10 年!京东店铺全量商品接口实战开发:从分页优化、SKU 关联到数据完整性闭环
linux·网络·数据库·windows·爬虫·python
ACERT3332 小时前
5.吴恩达机器学习—神经网络的基本使用
人工智能·python·神经网络·机器学习
韩立学长3 小时前
【开题答辩实录分享】以《基于python的奶茶店分布数据分析与可视化》为例进行答辩实录分享
开发语言·python·数据分析
天若有情6733 小时前
C++空值初始化利器:empty.h使用指南
开发语言·c++
远远远远子3 小时前
类与对象 --1
开发语言·c++·算法
无敌最俊朗@3 小时前
C/C++ 关键关键字面试指南 (const, static, volatile, explicit)
c语言·开发语言·c++·面试
2401_831501733 小时前
Python学习之day03学习(文件和异常)
开发语言·python·学习