sphinx：python項目文檔自動生成

Sphinx:

---

發音：

DJ音標發音： [sfiŋks] KK音標發音： [sfɪŋks]

單詞自己釋義：

an ancient imaginary creature with a lion's body and a woman's head

1. Mythology A figure in Egyptian myth having the body of a lion and the head of a man, ram, or hawk.
   【古埃及神話】 斯芬克斯：古代埃及神話中人面、公羊頭或鷹頭的獅身像
2. Greek Mythology A winged creature having the head of a woman and the body of a lion, noted for killing those who could not answer its riddle.
   【希臘神話】 斯芬克斯：古代希臘神話中帶翼的獅身女面怪物，專殺那些猜不出其謎語的人

---

Sphinx在此處是一個可自動生成python項目api的工具，使用起來也比較簡單，只須要在項目上進行簡單的配置，便可生成項目的api文檔（以下圖）

步驟：

1. 安裝sphinx

pip install sphinx

2. 在項目的開發過程當中

2.1注意在註釋中說清楚函數的用途描述，參數意義以及返回了什麼，例如：(在pycharm中，在函數名的下一行輸入3個引號後回車會自動生成函數描述的模板

2.2 在pycharm中設置文件頭及函數註釋的模板

2.2.1

• 文件頭模板設置
  ** File->settings->Editor->File and Code Templates->Python Script
  

• 函數知識模板設置
  ** File->Settings->Tools->Python integrated Tools->Docstring format，把該框選爲Google或nunpy等
  因numpy對於多個returns的支持較好，因此選用了numpy
  

3. 配置sphinx

3.1 在項目文檔下新建一個文件夾，可命名爲doc （路徑 your_project_path/doc）

3.2 進入doc文件夾下的命令行窗口，輸入sphinx-quickstart進行配置 (文中一下的命令行，如無特殊說明，皆是在doc路徑下執行)

配置你的項目名，版本，等
在此處的選項中，除了autodoc使用非默認的選項，選了y，其餘的，皆使用默認項。配置項選錯了也不要緊，最後均可以在conf.py中更改

sphinx-quickstart

Welcome to the Sphinx 1.8.3 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: 

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]: 

The project name will occur in several places in the built documentation.
> Project name: test_sphinx
> Author name(s): testname
> Project release []: 0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: 

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst". Only files with this suffix are considered documents.
> Source file suffix [.rst]: 

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]: 
Indicate which of the following Sphinx extensions should be enabled:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: 
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: 
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: 
> coverage: checks for documentation coverage (y/n) [n]: 
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: 
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: 
> 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]: 

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]: 
> Create Windows command file? (y/n) [y]: 

Creating file .\conf.py.
Creating file .\index.rst.
Creating file .\Makefile.
Creating file .\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file .\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

在doc文件夾下獲得以下

3.3 配置生成各個py文件的rst文件，在doc下生成一個rst文件夾

sphinx-apidoc -o [生成rst的位置] [項目代碼的位置] -f(強制從新覆蓋寫，不然會檢測，若是有同名文件存在，會跳過不更新)
sphinx-apidoc -o rst ../src

3.4 修改conf.py文件

3.4.1 將conf.py中第15-17行的註釋取消，並講第17行的路徑改成源代碼的所在路徑

import os
import sys
sys.path.insert(0, os.path.abspath('../src'))

3.4.2 若是源代碼中引入了pandas，numpy等比較大的包，須要在conf.py中作相應的設置，不然會有import errpr之類的報錯

autodoc_mock_imports = ["pandas","pyecharts"]

3.4.3 爲了google的docstring換行的展現，更改

extensions = ['sphinx.ext.autodoc','sphinx.ext.napoleon']

3.5 生成html

make html

在doc下的子文件夾中會生成若干html，打開index.html便可查閱相關的函數API