sphinx doc 文檔生成腳手架工具

sphinx 在python 語言開發中，是一個使用的比較多文檔生成腳手架工具，我們幫助我們生成
專業的幫助文檔，同時也有遠端的免費saas 托管服務，方便分發

安裝

sphinx 的安裝好多方便，mac 的可以使用brew，或者我們可以使用pip 安裝,詳細的可以參考官方文檔

• mac brew 安裝方法

 

brew install sphinx-doc

• pip 安裝

pip install -U sphinx

簡單demo

sphinx 提供了一個快速生成文檔的命令，使用sphinx-quickstart 我們可以快速生成一個可用的文檔項目

• sphinx-quickstart

sphinx-quickstart

 

效果

歡迎使用 Sphinx 2.1.0 快速配置工具。

​

請輸入接下來各項設置的值（如果方括號中指定了默認值，直接

按回車即可使用默認值）。

​

已選擇根路徑：.

​

布置用於保存 Sphinx 輸出的構建目錄，有兩種選擇。

一是在根路徑下創建“_build”目錄，二是在根路徑下創建“source”

和“build”兩個獨立的目錄。

> 獨立的源文件和構建目錄（y/n） [n]: y

​

項目名稱會出現在文檔的許多地方。

> 項目名稱: dalongrongdemo

> 作者名稱: dalong

> 項目發行版本 []: v1.0

​

如果用英語以外的語言編寫文檔，你可以在此按語言代碼選擇語種。

Sphinx 會把內置文本翻譯成相應語言的版本。

​

支持的語言代碼列表見：

http://sphinx-doc.org/config.html#confval-language。

> 項目語種 [en]: 

​

創建文件 ./source/conf.py。

創建文件 ./source/index.rst。

創建文件 ./Makefile。

創建文件 ./make.bat。

​

完成：已創建初始目錄結構。

​

你現在可以填寫主文檔文件 ./source/index.rst 並創建其他文檔源文件了。用 Makefile 構建文檔，像這樣：

 make builder

此處的“builder”是支持的構建器名，比如 html、latex 或 linkcheck。

 

• 生成html 頁面

  sphinx 使用make 進行項目管理，make 可以列出完整的命令

make html

正在運行 Sphinx v2.1.0

making output directory... 完成

構建 [mo]：0 個 po 文件的目標文件已過期

構建 [html]中: 1 個源文件的目標文件已過期

updating environment: 1 added, 0 changed, 0 removed

reading sources... [100%] index 

查找當前已過期的文件……沒有找到

pickling environment... 完成

checking consistency... 完成

preparing documents... 完成

寫入輸出……[100%] index 

生成索引…… genindex

寫入附加頁面…… search

復制靜態文件……完成

復制額外文件……完成

導出 English (code: en) 的搜索索引……完成

導出對象清單……完成

構建 成功.

HTML 頁面保存在 build/html 目錄。

 

生成的內容

tree build 

build

├── doctrees

│ ├── environment.pickle

│ └── index.doctree

└── html

    ├── _sources

    │ └── index.rst.txt

    ├── _static

    │ ├── alabaster.css

    │ ├── basic.css

    │ ├── custom.css

    │ ├── doctools.js

    │ ├── documentation_options.js

    │ ├── file.png

    │ ├── jquery-3.2.1.js

    │ ├── jquery.js

    │ ├── language_data.js

    │ ├── minus.png

    │ ├── plus.png

    │ ├── pygments.css

    │ ├── searchtools.js

    │ ├── underscore-1.3.1.js

    │ └── underscore.js

    ├── genindex.html

    ├── index.html

    ├── objects.inv

    ├── search.html

    └── searchindex.js

頁面效果

 

• 修改皮膚
  sphinx 默認提供了好多可選的皮膚，我們可以通過修改conf.py 調整，比如：

html_theme = "classic"

重新構建之后的效果

 

https://sphinx-themes.org/ 網站提供了好多可選的皮膚，提供sphinx_rtd_theme 是用的比較多的一個皮膚

sphinx_rtd_theme 皮膚的安裝使用

一般來說我們直接通過pip install sphinx_rtd_theme 然后在執行make html 就可以了，但是可能會有問題，以下會比較保險的安裝方法

• 配置venv

 

python3 -m venv venv

• 激活虛擬環境

source venv/bin/activate

• 安裝皮膚

pip install sphinx_rtd_theme

• 修改conf.py

html_theme = 'sphinx_rtd_theme'

• 重新構建

make html

• 效果

 

說明

對於生成的html 文件，我們可以通過minio s3 或者nexus 的raw repo，提供方便的資源訪問，同時也可以直接使用github，或者readthedocs
進行托管

參考資料

http://www.sphinx-doc.org
https://sphinx-themes.org/
https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html