使用sphinx快速为你python注释生成API文档
sphinx简介
sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发。新版的Python3文档就是由sphinx生成的,并且它已成为Python项目首选的文档工具,同时它对C/C++项目也有很好的支持。更多详细特性请参考spinx官方文档,本篇博客主要介绍如何快速为你的Python注释生成API文档。
环境
需要安装python
安装sphinx
pip install sphinx
1
实例
新建一个项目
目录结构如上图所示,doc目录使用来存放API文档,src目录是用来存放项目的源码。
src目录下的源码
#coding=UTF-8
class Demo1():
"""类的功能说明"""
def add(self,a,b):
"""两个数字相加,并返回结果"""
return a+b
def google_style(arg1, arg2):
"""函数功能.
函数功能说明.
Args:
arg1 (int): arg1的参数说明
arg2 (str): arg2的参数说明
Returns:
bool: 返回值说明
"""
return True
def numpy_style(arg1, arg2):
"""函数功能.
函数功能说明.
Parameters
----------
arg1 : int
arg1的参数说明
arg2 : str
arg2的参数说明
Returns
-------
bool
返回值说明
"""
return True
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
demo1文件,主要使用了两种不同的Python注释分格。对于简单的例子和简单的函数以及文档说明,使用google style显得更为简洁,而对于比较复杂详细的文档说明numpy style更为流行。
#coding=UTF-8
def my_function(a, b):
"""函数功能说明
>>> my_function(2, 3)
6
>>> my_function('a', 3)
'aaa'
"""
return a * b
1
2
3
4
5
6
7
8
9
10
11
12
demo2文件的注释看起来像Python命令行输入的文档字符串,主要是用来检查命令输出是否匹配下行的内容,它允许开发人员在源码中嵌入真实的示例和函数的用法,还能确保代码被测试和工作。
使用sphinx建立API文档项目
进入到doc目录下
cd 项目路径/doc
1
输入sphinx-quickstart命令,会输出选项
> Root path for the documentation [.]: sphinx_demo
> Separate source and build directories (y/n) [n]: y
> Name prefix for templates and static dir [_]:
> Project name: sphinx_demo
> Author name(s): sphinx demo
> Project version []: 1.0
> Project release [1.0]:
> Project language [en]: zh_CN
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> 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
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
因为我们需要从Python代码的注释中自动导出API文档,所以需要将autodoc: automatically insert docstrings from modules (y/n) [n]: y如果忘记设置,可以在conf.py中的extensions中添加'sphinx.ext.autodoc'。选项后面没有输入的,直接按回车键使用默认设置。选项后面有输入的,按照我的设置即可,如果不使用中文文档,可以在language配置中使用默认设置。设置完成之后,可以看到如下的目录结构
后面如果需要修改配置,选项在source/conf.py文件中修改即可。
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax']
1
2
3
4
5
6
通过设置conf.py中的extensions,可以为sphinx添加额外的扩展,如果想要将html文档转换为PDF,只需要先安装扩展,然后再此处添加即可使用。由于我们的注释代码主要同时支持google style和numpy style,所以我们需要添加一个扩展来支持。
sphinx.ext.napoleon
1
为源码生成html文件
修改source/conf.py文件的19-21行
import os
import sys
sys.path.insert(0, os.path.abspath('../../../src'))#指向src目录
1
2
3
将命令行切换到doc目录下,执行以下命令
sphinx-apidoc -o sphinx_demo/source ../src/
>Creating file sphinx_demo/source\demo1.rst.
>Creating file sphinx_demo/source\demo2.rst.
>Creating file sphinx_demo/source\modules.rst.
1
2
3
4
清理文件
cd sphinx_demo
make clean
>Removing everything under 'build'...
1
2
3
生成html文件
make html
1
请确保这一步没有输出error和exception
打开build/html/index.html
8. 修改API的主题
打开source/conf.py文件,找到html_theme = 'alabaster',修改即可,sphinx官方提供了几种主题可以进行选择,sphinx主题设置
相关错误解决办法
SyntaxError:Non-ASCII character '\xba' in file .....py
在*.py文件的第一行添加#coding=UTF-8
Encoding error:'utf8' codec can't decode byte 0xc0 in position 44:invalid start byte
确保*.py文件的编码格式为utf-8,通过notepad++可以进行查看,如果不是请修改为utf-8格式
添加sphinx.ext.napoleon后报Exception occurred ....return translator['sphinx'].ugettext(message) KeyError:'sphinx'
Sphinx1.3,napoleon扩展使用sphinx.ext.napoleon,Sphinx <= 1.2使用sphinxcontrib.napoleon
---------------------
作者:修炼之路
来源:CSDN
原文:https://blog.csdn.net/sinat_29957455/article/details/83657029
版权声明:本文为博主原创文章,转载请附上博文链接!
转载于:https://www.cnblogs.com/ExMan/p/10790285.html
使用sphinx快速为你python注释生成API文档相关推荐
- 使用sphinx快速为你python注释生成API(html)文档
sphinx简介 sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发.新版的Python3文档就是由sphinx生成的 ...
- XDoc 基于Java注释生成API文档
XDoc 基于Java注释生成API文档 <!--加入maven依赖--> <dependency><groupId>com.github.treeleafj< ...
- 使用sphinx为python注释生成docAPI文档
sphinx简介 sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发. 新版的Python3文档就是由sphinx生成 ...
- 超详细!使用swagger自动生成Api文档(swagger-ui)
介绍 swagger是什么? swagger-ui 使用swagger-ui 简单使用 swagger api注解 本文参考: 介绍 这里是一些介绍,如果想直接看如何使用,请直接跳过这部分.但如果有时 ...
- python生成api文档_sphinx生成python文档
**sphinx比较适合为Python生成文档** 1.安装sphinx ```shell pip install sphinx sphinx-autobuild sphinx_rtd_theme ` ...
- 根据注释生成项目文档
根据注释生成项目文档 根据文档注释,快速的生成一个文档 方便对整个项目有一个清晰的认知 生成外部文档的用法 使用默认编码生成 javadoc 源文件 -d 目标路径 可能会出现的错误 指定编码生成 j ...
- python新建word文档_使用Python 自动生成 Word 文档的教程
当然要用第三方库啦 :) 使用以下命令安装: pip install python-docx 使用该库的基本步骤为: 1.建立一个文档对象(可自动使用默认模板建立,也可以使用已有文件). 2.设置文档 ...
- python自动生成和读取word_使用Python自动生成Word文档的教程
当然要用第三方库啦 :) 使用以下命令安装: pip install python-docx 使用该库的基本步骤为: 1.建立一个文档对象(可自动使用默认模板建立,也可以使用已有文件). 2.设置文档 ...
- python实现生成word文档并转为pdf
python实现生成word文档,格式转为pdf 使用的是python-docx模块,在生成word文档后转为pdf格式是使用的是docx2pdf中的convert(使用convert转换时,要先创建 ...
最新文章
- wand java源码_ImageMagick使用for java(im4java)
- mysql进程SHOW PROCESSLIST详解Command命令状态
- android魅族轮播图,用angularjs模仿魅族官网的图片轮播功能
- 类型的本质和函数式实现
- 一体化市场谋定国际品牌贸易 对话国际农民丰收节贸易会
- 【redis】批量删除key
- uva 10534——Wavio Sequence
- 译林 五年级上 单词_牛津译林版九年级英语上Unit1单元重点单词、词组和句型总结...
- 康博(COMPUWARE)软件公司简介
- java打印出货单_送货单,出货单打印用什么软件,含操作方法
- facebook piexl 像素追踪
- steam游戏文件夹在哪儿?
- 特斯拉进化论:舍命狂奔背后的生存哲学
- 体重计c语言程序,利用MSP430F149和HX711模块制作体重秤?
- CWRU数据集-美国西储大学轴承数据
- Android:BroadCast Receiver
- Androidstudio之TextView点击变色
- java上传文件限速_java HttpClient 上传限速(避免宽带占用过高)
- 浙江大学软件学院三维动画与交互技术考试概念整理
- 2022双十一新规则解读
热门文章
- UWP 响应键盘组合快捷键
- C# 匿名委托、匿名方法、匿名对象、Lambda表达式
- Vue基础学习(一)------内部指令
- 【转】sip中的subscribe和notify扩展应用技术
- poj 3258 River Hopscotch 【二分】
- [物理学与PDEs]第1章第4节 电磁能量和电磁动量, 能量、动量守恒与转化定律 4.3 电磁能量 (动量) 密度, 电磁能量流 (动量流) 密度...
- TF-IDF理解及其Java实现
- mysql数据库存储过程及调用方法
- VSCode配合eslint进行JavaScript质量检查
- powercmd注册码