使用sphinx快速为你python注释生成API文档
sphinx簡(jiǎn)介
sphinx是一種基于Python的文檔工具，它可以令人輕松的撰寫(xiě)出清晰且優(yōu)美的文檔，由Georg Brandl在BSD許可證下開(kāi)發(fā)。新版的Python3文檔就是由sphinx生成的，并且它已成為Python項(xiàng)目首選的文檔工具，同時(shí)它對(duì)C/C++項(xiàng)目也有很好的支持。更多詳細(xì)特性請(qǐng)參考spinx官方文檔，本篇博客主要介紹如何快速為你的Python注釋生成API文檔。
環(huán)境
需要安裝python
安裝sphinx
pip install sphinx
1
實(shí)例
新建一個(gè)項(xiàng)目
目錄結(jié)構(gòu)如上圖所示，doc目錄使用來(lái)存放API文檔，src目錄是用來(lái)存放項(xiàng)目的源碼。
src目錄下的源碼
#coding=UTF-8
class Demo1():
"""類(lèi)的功能說(shuō)明"""
def add(self,a,b):
"""兩個(gè)數(shù)字相加，并返回結(jié)果"""
return a+b
def google_style(arg1, arg2):
"""函數(shù)功能.
函數(shù)功能說(shuō)明.
Args:
arg1 (int): arg1的參數(shù)說(shuō)明
arg2 (str): arg2的參數(shù)說(shuō)明
Returns:
bool: 返回值說(shuō)明
"""
return True
def numpy_style(arg1, arg2):
"""函數(shù)功能.
函數(shù)功能說(shuō)明.
Parameters
----------
arg1 : int
arg1的參數(shù)說(shuō)明
arg2 : str
arg2的參數(shù)說(shuō)明
Returns
-------
bool
返回值說(shuō)明
"""
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注釋分格。對(duì)于簡(jiǎn)單的例子和簡(jiǎn)單的函數(shù)以及文檔說(shuō)明，使用google style顯得更為簡(jiǎn)潔，而對(duì)于比較復(fù)雜詳細(xì)的文檔說(shuō)明numpy style更為流行。
#coding=UTF-8
def my_function(a, b):
"""函數(shù)功能說(shuō)明
>>> 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文件的注釋看起來(lái)像Python命令行輸入的文檔字符串，主要是用來(lái)檢查命令輸出是否匹配下行的內(nèi)容，它允許開(kāi)發(fā)人員在源碼中嵌入真實(shí)的示例和函數(shù)的用法，還能確保代碼被測(cè)試和工作。
使用sphinx建立API文檔項(xiàng)目
進(jìn)入到doc目錄下
cd 項(xiàng)目路徑/doc
1
輸入sphinx-quickstart命令，會(huì)輸出選項(xiàng)
> 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
因?yàn)槲覀冃枰獜腜ython代碼的注釋中自動(dòng)導(dǎo)出API文檔，所以需要將autodoc: automatically insert docstrings from modules (y/n) [n]: y如果忘記設(shè)置，可以在conf.py中的extensions中添加'sphinx.ext.autodoc'。選項(xiàng)后面沒(méi)有輸入的，直接按回車(chē)鍵使用默認(rèn)設(shè)置。選項(xiàng)后面有輸入的，按照我的設(shè)置即可，如果不使用中文文檔，可以在language配置中使用默認(rèn)設(shè)置。設(shè)置完成之后，可以看到如下的目錄結(jié)構(gòu)
?
后面如果需要修改配置，選項(xiàng)在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
通過(guò)設(shè)置conf.py中的extensions，可以為sphinx添加額外的擴(kuò)展，如果想要將html文檔轉(zhuǎn)換為PDF，只需要先安裝擴(kuò)展，然后再此處添加即可使用。由于我們的注釋代碼主要同時(shí)支持google style和numpy style，所以我們需要添加一個(gè)擴(kuò)展來(lái)支持。
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目錄下，執(zhí)行以下命令
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
請(qǐng)確保這一步?jīng)]有輸出error和exception
打開(kāi)build/html/index.html
8. 修改API的主題
打開(kāi)source/conf.py文件，找到html_theme = 'alabaster'，修改即可，sphinx官方提供了幾種主題可以進(jìn)行選擇，sphinx主題設(shè)置
相關(guān)錯(cuò)誤解決辦法
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，通過(guò)notepad++可以進(jìn)行查看，如果不是請(qǐng)修改為utf-8格式
添加sphinx.ext.napoleon后報(bào)Exception occurred ....return translator['sphinx'].ugettext(message) KeyError：'sphinx'
Sphinx1.3，napoleon擴(kuò)展使用sphinx.ext.napoleon，Sphinx <= 1.2使用sphinxcontrib.napoleon
---------------------
作者：修煉之路
來(lái)源：CSDN
原文：https://blog.csdn.net/sinat_29957455/article/details/83657029
版權(quán)聲明：本文為博主原創(chuàng)文章，轉(zhuǎn)載請(qǐng)附上博文鏈接！
轉(zhuǎn)載于:https://www.cnblogs.com/ExMan/p/10790285.html
總結(jié)
以上是生活随笔為你收集整理的使用sphinx快速为你python注释生成API文档的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。
- 上一篇： 笔记：Java虚拟机运行时数据区
- 下一篇： Python之IO模式 阻塞式io 非阻