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