使用sphinx爲python註釋生成docAPI文檔

時間 2019-11-06

標籤使用 sphinx python 註釋生成 docapi 文檔欄目 MySQL 简体版

原文原文鏈接

sphinx簡介

sphinx是一種基於Python的文檔工具，它能夠使人輕鬆的撰寫出清晰且優美的文檔，由Georg Brandl在BSD許可證下開發。
新版的Python3文檔就是由sphinx生成的，而且它已成爲Python項目首選的文檔工具，同時它對C/C++項目也有很好的支持。
更多詳細特性請參考spinx官方文檔html

sphinx安裝

須要安裝python
pip install sphinx

示例

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

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命令行輸入的文檔字符串，
主要是用來檢查命令輸出是否匹配下行的內容，
它容許開發人員在源碼中嵌入真實的示例和函數的用法，還能確保代碼被測試和工做。

#coding=UTF-8  
def my_function(a, b):
"""函數功能說明

 >>> my_function(2, 3)
 6
 >>> my_function('a', 3)
 'aaa'

"""
return a * b

使用sphinx創建API文檔項目git

進入到doc目錄下github

cd 項目路徑/docapi
輸入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

爲源碼生成html文件函數

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

import os
import sys
sys.path.insert(0, os.path.abspath('../../../src'))  # 指向src目錄

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.htmlui
修改API的主題
打開source/conf.py文件，找到html_theme = 'alabaster'，修改便可，sphinx官方提供了幾種主題能夠進行選擇，sphinx主題設置google

使用sphinx爲python註釋生成docAPI文檔

sphinx簡介

sphinx安裝

示例

相關錯誤解決辦法