使用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

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/264100.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

c#中使用ref和out传值

c#中使用ref和out传值 首先,如果不使用这两个关键字,那是什么样 呢?看下面的例子:使用ref:using System; class Test {     static void Swap(ref int x, ref int y)     {         int temp x;         x y;         y temp;     }  …

python临床数据_从临床试验中获取数据

我正在开发一个小Python函数来从clinicalTrials.gov中获取数据。从每个研究记录中&#xff0c;我想从中找出研究的目标条件。例如&#xff0c;对于this研究记录&#xff0c;我需要以下内容&#xff1a;conditions [Rhinoconjunctivitis, Rhinitis, Conjunctivitis. Allergy]然…

Jass 技能模型定义(转)

Jass是什么&#xff1f;先阐释一下什么是jass吧&#xff0c;百度&#xff1a;JASS&#xff08;正确地说是JASS 2&#xff09;是魔兽3的程序语言&#xff0c;用于控制游戏和地图的进行&#xff0c;也是魔兽游戏和地图的基础。 地图编辑器中摆放的单位(Unit)&#xff0c;区域(Reg…

[原]第一次遭遇Oracle的Bug,纪念一下 |ORA-00600 kmgs_pre_process_request_6|

今天尝试调整一下Oracle的Large Pool Size&#xff0c;希望使rman的速度提升&#xff0c; alter system set large_pool_size80m ; 突然Oracle 实例挂掉了&#xff0c;查看alert file 发现如下 Wed Dec 16 11:14:49 2009 Errors in file /u01/app/admin/mydb/bdump/mydb_mman_…

表格过滤器_不用记账软件也可以记录支出明细,这个在线协同表格很方便

像我们这种中小团队&#xff0c;以前就用 Excel 来记录团队日常的一些支出情况&#xff0c;虽然有很多模板可以套用&#xff0c;但感觉还是有些不便之处&#xff0c;比如在表格里无法记录太多文字&#xff1b;添加发票凭证也不方便&#xff1b;对于不同数据的切换查看也缺乏灵活…

喜马拉雅第三方客户端开发(接口和接口数据解析)。

前言&#xff1a;最近闲来无事&#xff0c;看了网上豆瓣的第三方客户端&#xff0c;手有点痒&#xff0c;决定自己动手开发一个客户端&#xff0c;比较了荔枝和喜马拉雅&#xff0c;决定开发喜马拉雅的第三方客户端。 客户端使用了WPF开发。 1.抓取接口&#xff1b; 首先得解决…

life list 2010

1. water -1.no water-warm water.less 2. anything - very kindly 3. clean - any room. 4.money is working,no lazy. 转载于:https://www.cnblogs.com/byeday/archive/2009/12/16/1625902.html

聚合复合_聚合复合微生物菌剂的功能

不点蓝字关注我飞走啦&#xff01;在经营肥料上来讲&#xff0c;大家都知道做复合微生物菌剂&#xff0c;不仅可以活化疏松土壤&#xff0c;而且在各种作物上抗逆、防病、增产的效果都非常的好。问为什么说大家都要重点使用聚合微生物菌剂呢&#xff1f;答因为聚合微生物菌剂和…

Linux命令 — 设置或查看网络配置命令ifconfig

1. 命令介绍命令格式&#xff1a;ifconfig 【interface】 【options】address主要参数&#xff1a;interface&#xff1a;网络接口名up&#xff1a;打开网络接口down&#xff1a;关闭网络接口broadcast&#xff1a;设置网络接口的广播地址netmask&#xff1a;设置网络接口的子网…

代理模式详解(静态代理和动态代理的区别以及联系)

原文链接:https://www.cnblogs.com/takumicx/p/9285230.html 1. 前言 代理模式可以说是生活中处处可见。比如说在携程上定火车票,携程在这里就起到了一个代理的作用,比起我们在官网上或者直接去柜台订票&#xff0c;携程可以为用户提供更多人性化的选择。再比如代购,我自己的mb…

unity自动生成敌人_unity 2d AI 敌人 自动追踪(1)

今天介绍第一种只靠 c# 代码的 简单 AI 敌人 追踪方法&#xff1a;简单粗暴 &#xff0c;上代码1&#xff0c;新建对象2&#xff0c;代码如下&#xff1a;using System.Collections;using System.Collections.Generic;using UnityEngine;public class AI : MonoBehaviour{publi…

一个简单的HelloWorld程序

/* * 编译器:  VC6.0 * 类 型:  C语言 */ 1 #include <stdio.h>//#includes代表是C预处理指令,stdio.h代表是在此行位置键入了库文件stdio.h的完整内容,是标准输入输出头文件,< and >代表是直接从库文件加载stdio.h文件。2 3 intmain(void)//int代表此main…

sass 安装配置和使用

一、什么是SASSSASS在CSS的基础上做了一些扩展&#xff0c;使用SASS你可以使用一些简单的编程思想进来编写CSS。比如&#xff0c;SASS中可以定义变量、混合、嵌套以及 函数等功能。只不过SASS不像CSS&#xff0c;可以直接运用到项目中&#xff0c;如果你需要将样式运用到项目中…

为什么我的对象被 IntelliJ IDEA 悄悄修改了?

背景 最近&#xff0c;在复习JUC的时候调试了一把ConcurrentLinkedQueue的offer方法&#xff0c;意外的发现Idea在debug模式下竟然会 “自动修改” 已经创建的Java对象&#xff0c;当时觉得这个现象很是奇怪&#xff0c;现在把问题的原因以及解决过程记录下来&#xff0c;希望你…

python加密程序_Python加密程序

展开全部alpabcdefghijklmnopqrstuvwxyz0123456789 def num2alp(c):a alp[c]return(a)def alp2num(d):if d ! :return((ord(d)-97)%37)else:return 36def envVigenere(key,plaintext):m len(plaintext)n len(key)etext ""for i in range(m):p plaintext[i]k k…

如何判断网通、电信、铁通IP地址分配段

从http://ftp.apnic.net/apnic/dbase/tools/ 获取地址 shell> wget http://ftp.apnic.net/apnic/dbase/tools/ripe-dbase-client-v3.tar.gz shell> tar xzvf ripe-dbase-client-v3.tar.gz shell> cd whois-3.1 shell> ./configure shell> make 完成上述编译安…

​std::multimap

2019独角兽企业重金招聘Python工程师标准>>> std::multimap multimap,是一个关联性容器,用于存放这样的元素,这些元素是由键以及关联的值组成.容器内容将根据元素的键进行排序.并且容器可以插入多个具有相同键的元素.接口 pair<const_iterator,const_iterator>…

python调用msfconsole全自动永恒之蓝攻击_MSF之MS17-010永恒之蓝漏洞利用

Loading...请注意&#xff0c;本文编写于 392 天前&#xff0c;最后修改于 116 天前&#xff0c;其中某些信息可能已经过时。# MSF之MS17-010永恒之蓝漏洞利用1. 准备阶段2. 扫描漏洞3. 漏洞攻击---## 准备阶段**实验准备环境&#xff1a;**攻击机&#xff1a;虚拟机kali系统IP…

容器部署解决方案Docker

一、Docker简介 1.1 虚拟化 【什么是虚拟化】 在计算机中&#xff0c;虚拟化&#xff08;英语&#xff1a;Virtualization&#xff09;是一种资源管理技术&#xff0c;是将计算机的各种实体资源&#xff0c;如服务器、网络、内存及存储等&#xff0c;予以抽象、转换后呈现出来&…

BREW做的第一个程序--Hello world!

这几天开始做BREW开发了&#xff0c;刚开始挺晕的。又是C指针&#xff0c;又是BREW的SDK文档&#xff0c;还有环境配置&#xff0c;一大堆东东&#xff0c;真是让人手忙脚乱。好不容易配好了环境&#xff0c;写出了第一个Hello world!程序。感觉还不错&#xff0c;就把代码和想…