Python 這個庫可快速生成文檔

安裝 sphinx 庫
簡單示例（ Spninx 使用）
步驟一：Sphinx 創建出基礎配置
步驟二：配置項目入口 index.rst
步驟三：生成項目文檔
步驟四：展示出來
小小總結

Sphinx 簡介

Sphinx 是一種工具，是一個有趣 python 的第三方庫，它允許程序員以純文本格式編寫文檔，Spninx 可以輕鬆生成各種格式的輸出，比如 html，pfd，等等。純文本的文檔方便使用版本管理工具進行跟蹤。純文本文檔對不同系統之間的協作者也非常有用，純文本是當前可以採用的最便捷的格式之一，不然 markdown 格式咋那麼火呢，不是沒有道理的。

程序員最討厭的兩件事：

自己寫代碼文檔
別人的代碼沒文檔

正經寫文檔確實麻煩，爲啥麻煩呢？因爲很長時間程序員寫代碼和寫文檔是完全獨立分開的，這說起來就是兩份工作量，最不能忍受的還是變化帶來的負擔，代碼是可能經常變動的，代碼變動之後，含義自然就可能不一樣，或者新加了了功能，文檔如果還要手動跟進的話，最喜歡偷懶的程序員自然就不願了。

我們迴歸本源，程序員這討厭的兩件事說明了什麼？

心有餘而力不足。心裏還是想寫文檔的，就是太累了。

所以，對此我們有解決方案嗎？

有，最核心的就是代碼即文檔，根據代碼來生成文檔。

這個 golang 在語言工具包裏就整合了 go doc 這樣的工具，能夠根據代碼和代碼裏的註釋生成一個漂亮的文檔。

Python 也有自己的方案，解決文檔就是 Sphinx ，Python3.x 官方的文檔就是用這個生成的。所以，如果你的也是 Python 項目，那麼可以生成一個和官方文檔同款的文檔項目，非常實用和拉風。

Sphinx 怎麼用？

先給大家看一張我本地生成文檔項目的圖，提提興趣：

使用這個小工具，你就不用專門寫文檔項目了，只需要寫好代碼就好，代碼即文檔。

安裝 sphinx 庫

安裝非常方便，就是一個簡單的 Python 三方庫，用 pip 安裝就行了：

pip install Sphinx

安裝完之後呢，應該有四個二進制文件：

sphinx-apidoc
sphinx-autogen
sphinx-build
sphinx-quickstart

如果呢，你沒有找到這四個二進制文件，那麼可以直接去找對應的 python 文件：

build.py
make_mode.py
quickstart.py

簡單示例（ Spninx 使用）

搞了一個最簡單的示例，項目根目錄是 ~/qiya/python-tools/ ，下面都是以此目錄爲基礎，下面的是我自己創建的目錄，搞了幾個簡單的目錄，common，misc 是項目的代碼目錄，docs 是我預定的專門放文檔的目錄。

root@ubuntu:~/qiya/python-tools# tree 
.
├── common
│   ├── demo.py
│   └── __init__.py
├── docs
│   └── __init__.py
├── misc
│   └── __init__.py
│   └── tools.py
└── README.md

我先準備好演示用的代碼項目：

demo 類文件：

tools 函數文件：

步驟一：Sphinx 創建出基礎配置

執行 `sphinx-quickstart`

使用sphinx-quickstart 可以直接做初始化，能夠完成最簡單的配置，生成一些最基礎的配置文件。

$ cd docs/
$ sphinx-quickstart

執行完這個命令，需要配置一些操作，信息如下：

sphinx-quickstart 命令執行完成之後，下面全都是自動生成的文件：

root@ubuntu:~/qiya/python-tools/docs# tree 
.
├── build
├── __init__.py
├── make.bat
├── Makefile
└── source
    ├── conf.py
    ├── index.rst
    ├── _static
    └── _templates

特意說下，最重要的就是兩個文件：

source/conf.py ：這個是 Sphinx 的配置，包括主題的設置，文檔的生成形式，都可以在這裏配置；
source/index.rst ：這個是項目的主頁文件，rst 語法，類似於 markdown，都是一種標記類文檔語言；

sphinx-quickstart 執行完之後呢，基礎的東西是給你準備好了，接下來就是要根據自身的情況來配置。首先要看的就是 conf.py 這個配置文件，我們的目錄是：

root@ubuntu:~/qiya/python-tools# tree 
.
├── common
│   ├── demo.py
│   └── __init__.py
├── docs
│   ├── build
│   ├── __init__.py
│   ├── make.bat
│   ├── Makefile
│   └── source
│       ├── conf.py
│       ├── index.rst
│       ├── _static
│       └── _templates
├── misc
│   ├── __init__.py
│   └── tools.py
└── README.md

配置 conf.py 文件

所以呢，我們要讓 conf.py 找到代碼，那麼就要添加好路徑，在最開頭修改，如下：

import sys
from os.path import abspath, dirname
# 爲什麼是上三層目錄呢？conf.py 這個文件和根目錄不就隔着三層目錄嘛
sys.path.insert(0, dirname(dirname(dirname(abspath(__file__)))))

這樣 Sphinx 就能找到你想要自動生成文檔的代碼了。下一步，添加 extensions ，說明咱們的文檔可以自動生成：

# 指明用 autodoc 的形式生成
extensions = [
        'sphinx.ext.autodoc'
]
# 指明用 sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'

sphinx_rtd_theme 這個主題不是默認的，這個是一個比較好看的主題，這個可以直接用 pip 安裝即可：

$ pip install sphinx_rtd_theme

conf.py 修改的樣子如下：

步驟二：配置項目入口 index.rst

這個 index.rst 文件是入口，項目文檔怎麼生成，生成什麼格式，就是這個文件裏配置的（這裏的配置是要和 conf 對應着來）。

************
Demo
************
common 公共庫
=================
.. automodule:: common.demo
   :members:
misc 庫
=================
.. automodule:: misc.tools
   :members:

解釋下，這裏的 common.demo 和 misc.tools 模塊對應了 py 文件。這個怎麼才能找到這兩個模塊，這個就跟你配置 conf.py 裏面的 path 配置有關。

步驟三：生成項目文檔

執行命令：

$ cd docs/
$ sphinx-build source/ build/

執行這個命令，就會自動去搜索代碼，生成文檔項目，默認生成的是 html 的文件。

這裏順帶提一下，如果你想生成其他格式的項目文檔，比如純文本格式，那麼可以執行：

$ cd docs/
$ sphinx-build -b text source/ build/

純文本格式如下：

步驟四：展示出來

怎麼看到效果呢？演示的話，開一個靜態服務器就行，給大家演示一個 python 3 一鍵起一個靜態服務器的命令：

$ python3 -m http.server 9000

顯示效果：

小小總結

希望大家寫好代碼，名字易讀，註釋規範，這樣就自然有好的文檔了。還有就是，這個 Sphinx 工具其實不僅適用於 Python，其他語言也能適用，大家可以探索。關鍵思考：代碼即文檔。

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/1wDHw0p1Tf3fMCdBk6cyhQ