sphinx簡介

sphinx是一種基于Python的文檔工具，它可以令人輕松的撰寫出清晰且優美的文檔，由Georg Brandl在BSD許可證下開發。

新版的Python3文檔就是由sphinx生成的，并且它已成為Python項目首選的文檔工具，同時它對C/C++項目也有很好的支持。

更多詳細特性請參考spinx官方文檔
https://zh-sphinx-doc.readthedocs.io/en/latest/intro.html

sphinx安裝

需要安裝python

pip install sphinx

示例

1. 新建一個項目
目錄結構如下，doc目錄使用來存放API文檔，src目錄是用來存放項目的源碼

2.src目錄下的源碼

demo1文件

主要使用了兩種不同的Python注釋分格。對于簡單的例子和簡單的函數以及文檔說明，
使用google style顯得更為簡潔，而對于比較復雜詳細的文檔說明numpy style更為流行。

#coding=UTF-8 class Demo1(): """類的功能說明"""def add(self,a,b):"""兩個數字相加，并返回結果"""return a+bdef google_style(arg1, arg2):"""函數功能.函數功能說明.Args:arg1 (int): arg1的參數說明arg2 (str): arg2的參數說明Returns:bool: 返回值說明"""return Truedef numpy_style(arg1, arg2):"""函數功能.函數功能說明.Parameters----------arg1 : intarg1的參數說明arg2 : strarg2的參數說明Returns-------bool返回值說明"""return True

demo2文件

注釋看起來像Python命令行輸入的文檔字符串，主要是用來檢查命令輸出是否匹配下行的內容，它允許開發人員在源碼中嵌入真實的示例和函數的用法，還能確保代碼被測試和工作。

''' 遇到問題沒人解答？小編創建了一個Python學習交流QQ群：579817333 尋找有志同道合的小伙伴，互幫互助,群里還有不錯的視頻學習教程和PDF電子書！ ''' #coding=UTF-8 def my_function(a, b): """ 函數功能說明>>> my_function(2, 3)6>>> my_function('a', 3)'aaa' """ return a * b

3.使用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文件中修改即可

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.mathjax']

額外的擴展

通過設置conf.py中的extensions，可以為sphinx添加額外的擴展，如果想要將html文檔轉換為PDF，只需要先安裝擴展，然后再此處添加即可使用。

由于我們的注釋代碼主要同時支持google style和numpy style，所以我們需要添加一個擴展來支持。

sphinx.ext.napoleon

4.為源碼生成html文件

修改source/conf.py文件的19-21行

''' 遇到問題沒人解答？小編創建了一個Python學習交流QQ群：579817333 尋找有志同道合的小伙伴，互幫互助,群里還有不錯的視頻學習教程和PDF電子書！ ''' 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.

5.清理文件

cd sphinx_demo make clean>Removing everything under 'build'...

6.生成html文件

make html// 請確保這一步沒有輸出error和exception

7.打開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

總結

以上是生活随笔為你收集整理的使用sphinx为python注释生成docAPI文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。