sphinx簡介

sphinx是一種基於Python的文件工具，它可以令人輕鬆的撰寫出清晰且優美的文件，由Georg Brandl在BSD許可證下開發。新版的Python3文件就是由sphinx生成的，並且它已成為Python專案首選的文件工具，同時它對C/C++專案也有很好的支援。更多詳細特性請參考spinx官方文件，本篇部落格主要介紹如何快速為你的Python註釋生成API文件。

環境

• 需要安裝python
• 安裝sphinx

pip install sphinx

例項

1. 新建一個專案
   
   目錄結構如上圖所示，doc目錄使用來存放API文件，src目錄是用來存放專案的原始碼
   。
2. 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

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

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

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行

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