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文檔項目
1. 進入到doc目錄下
cd 項目路徑/doc
1. 輸入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配置中使用默認設置。

設置完成之后，可以看到如下的目錄結構
```

![](https://img2018.cnblogs.com/blog/885885/201910/885885-20191022174906524-83463060.png)  

* 后面如果需要修改配置，在選項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主題設置

使用sphinx為python注釋生成docAPI文檔

sphinx簡介

sphinx安裝

示例

coding=UTF-8

coding=UTF-8

相關錯誤解決辦法

免責聲明！