使用sphinx为python注释生成docAPI文档
sphinx简介
sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发。
新版的Python3文档就是由sphinx生成的,并且它已成为Python项目首选的文档工具,同时它对C/C++项目也有很好的支持。
更多详细特性请参考spinx官方文档
sphinx安装
- 需要安装python
- pip install sphinx
示例
新建一个项目
目录结构如下,
doc目录使用来存放API文档,
src目录是用来存放项目的源码src目录下的源码
- demo1文件
主要使用了两种不同的Python注释分格。对于简单的例子和简单的函数以及文档说明,
使用google style显得更为简洁,
而对于比较复杂详细的文档说明numpy style更为流行。
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
```
* demo2文件
```
注释看起来像Python命令行输入的文档字符串,
主要是用来检查命令输出是否匹配下行的内容,
它允许开发人员在源码中嵌入真实的示例和函数的用法,还能确保代码被测试和工作。
```
```python
coding=UTF-8
def my_function(a, b):
"""函数功能说明
>>> my_function(2, 3)
6
>>> my_function('a', 3)
'aaa'
"""
return a * b
```
使用sphinx建立API文档项目
- 进入到doc目录下
cd 项目路径/doc
- 输入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]:
```
```
因为我们需要从Python代码的注释中自动导出API文档,
所以需要将autodoc: automatically insert docstrings from modules (y/n) [n]: y
如果忘记设置,可以在conf.py中的extensions中添加'sphinx.ext.autodoc'。
选项后面没有输入的,直接按回车键使用默认设置。
选项后面有输入的,按照我的设置即可,
如果不使用中文文档,可以在language配置中使用默认设置。
设置完成之后,可以看到如下的目录结构
```

* 后面如果需要修改配置,在选项source/conf.py文件中修改即可
```python
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax']
```
* 额外的扩展
```text
通过设置conf.py中的extensions,可以为sphinx添加额外的扩展,
如果想要将html文档转换为PDF,只需要先安装扩展,然后再此处添加即可使用。
由于我们的注释代码主要同时支持google style和numpy style,所以我们需要添加一个扩展来支持。
```
```
sphinx.ext.napoleon
```
为源码生成html文件
- 修改source/conf.py文件的19-21行
import os
import sys
sys.path.insert(0, os.path.abspath('../../../src')) # 指向src目录
```
* 将命令行切换到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.
```
清理文件
cd sphinx_demo
make clean >Removing everything under 'build'...
生成html文件
make html // 请确保这一步没有输出error和exception
打开build/html/index.html
修改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
使用sphinx为python注释生成docAPI文档的更多相关文章
- 使用sphinx快速为你python注释生成API文档
sphinx简介sphinx是一种基于Python的文档工具,它可以令人轻松的撰写出清晰且优美的文档,由Georg Brandl在BSD许可证下开发.新版的Python3文档就是由sphinx生成的, ...
- 利用sphinx为python项目生成API文档
sphinx可以根据python的注释生成可以查找的api文档,简单记录了下步骤 1:安装 pip install -U Sphinx 2:在需要生成文档的.py文件目录下执行sphinx-apido ...
- .Net魔法堂:提取注释生成API文档
一.前言 在多人协作的项目中,除了良好的代码规范外,完整的API文档也相当重要.通过文档我们快速了解系统各模块的实际接口,及其使用场景.使用示例,一定程度上降低沟通成本,和减少后期维护中知识遗失等风险 ...
- .net 提取注释生成API文档 帮助文档
提取注释生成API文档 一.前言 在多人协作的项目中,除了良好的代码规范外,完整的API文档也相当重要.通过文档我们快速了解系统各模块的实际接口,及其使用场景.使用示例,一定程度上降低沟通成本,和 ...
- 注释生成Api文档
1.开发背景 最近一直在写dubbo接口,以前总是用word文档写接口描述然后发给别人.现在太多了,而且跟别人对接联调的人家急着用,根本没时间去写word文档.那就想想怎么用doc文档注释自动生成接口 ...
- ASP.NET Web API从注释生成帮助文档
默认情况下,ASP.NET Web API不从Controller的注释中生成帮助文档.如果要将注释作为Web API帮助文档的一部分,比如在帮助文档的Description栏目中显示方法注释中的su ...
- 使用Sandcastle 基于代码注释生成接口文档
一. 工具下载: 1. Sandcastle:Sandcastle是微软官方的文档生成工具,下载地址:http://www.codeplex.com/Sandcastle 2. SHFBGuidedI ...
- 快速根据注释生成接口文档网页工具——Apidoc的使用教程
1,安装Node.js的npm工具环境: 如有不懂,请看我的博客:“https://blog.csdn.net/sinat_28371057/article/details/81612661“ 2,n ...
- ASP.NET Web API根据代码注释生成Help文档
使用Visual Studio新建一个ASP.NET Web API项目,直接运行,查看Help文档可以看到如下的API帮助说明 如何在Description中显示描述. 1. 打开Controlle ...
随机推荐
- linux系统信息获取和上报
通过调用shell命令获取系统信息,如cpu个数,cpu/内存磁盘使用情况,网络信息等. #include <stdio.h> #include <stdlib.h> #inc ...
- 【HICP Gauss】数据库 数据库管理(shutdown 日志 连接命令)-5
数据库关闭终止Zengine进程关闭数据库 会导致无法预料的状态 建议shutdown关闭数据库 shutdown 模式1.normal默认 停止新请求 断开等待会话 关闭服务 终止主进程 需要连接发 ...
- Python Image库简单处理图像
直接列举几个常用的函数,可在 http://effbot.org/imagingbook/image.htm 中查看更多相关函数. from PIL import Image import numpy ...
- 一些替代Xshell的软件推荐
FinalShell: 面附上一些截图和官方连接: 官网:http://www.hostbuf.com/ FinalShell是一体化的的服务器,网络管理软件,不仅是ssh客户端,还是功能强大的开发, ...
- HashMap扩容死循环问题
原文:https://blog.csdn.net/Leon_cx/article/details/81911223 下面我们来模拟一下多线程场景下扩容会出现的问题: 假设在扩容过程中旧hash桶中有一 ...
- 快捷定位目录 z武器
z的源码在这里:https://github.com/rupa/z/blob/master/z.sh 1.把源码复制到你的用户目录下的z.sh文件, 2.然后用vim打开.bashrc这个目录,在最后 ...
- everything in javascript can act like an object,
- test20190904 JKlover
100+100+100=300.最后十分钟极限翻盘. 树链剖分 给一棵以1为根的有根树,开始只有1有标记. 每次操作可以给某个点打上标记,或者询问从某个点开始向上跳,遇到的第一个有标记的点. 对于 1 ...
- ora-00054资源正忙,但指定以nowait方式
select l.session_id,o.owner,o.object_name from v$locked_object l,dba_objects o where l.object_id=o.o ...
- C++中的类所占内存空间总结(转)
类所占内存的大小是由成员变量(静态变量除外)决定的,成员函数(这是笼统的说,后面会细说)是不计算在内的. 摘抄部分: 成员函数还是以一般的函数一样的存在.a.fun()是通过fun(a.this)来调 ...