# 使用 Sphinx 撰寫技術文檔

認識 Sphinx

Sphinx 是一個基於 Python 的文檔生成項目。最先只是用來生成 Python 的項目文檔，使用 reStructuredText 格式。但隨着項目的逐漸完善，不少非 Python 的項目也採用 Sphinx 做爲文檔寫做工具，甚至徹底能夠用 Sphinx 來寫書。

使用 Sphinx 生成文檔的優勢包括：

• 豐富的輸出格式: 支持輸出爲 HTML（包括 Windows 幫助文檔），LaTeX（能夠打印PDF版本）, manual pages（man 文檔）, 純文本等若干種格式；
• 完備的交叉引用: 語義化的標籤，並能夠自動化連接函數、類、引文、術語等；
• 明晰的分層結構: 輕鬆定義文檔樹，並自動化連接同級/父級/下級文章；
• 美觀的自動索引: 可自動生成美觀的模塊索引；
• 精確的語法高亮: 基於 Pygments 自動生成語法高亮；
• 開放的擴展: 支持代碼塊的自動測試，自動包含 Python 的模塊自述文檔，等等。

安裝 Sphinx

Sphinx 依賴於 Python，並提供了 Python 包，因此使用 pip3 安裝既可。這裏我只安裝了 sphinx 這個包。

# Sphinx
$ brew install python3
$ pip3 install -U Sphinx
複製代碼

這時，經過 bash 自動補全（連續兩下 tab），能夠看到有幾個命令，Sphinx 推薦使用 sphinx-quickstart，這是一個設置嚮導。

$ sphinx-
sphinx-apidoc      sphinx-autogen     sphinx-build       sphinx-quickstart
複製代碼

設置 Sphinx

運行 sphinx-quickstart，如下主要設置項目名稱，做者名稱以及語言（zh_CN）便可，其餘默認。

$ sphinx-quickstart
複製代碼

接下來會讓你選擇一些配置： 1). 設置文檔的根路徑（回車，使用默認設置）

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

請輸入接下來各項設置的值（若是方括號中指定了默認值，直接
按回車便可使用默認值）。

已選擇根路徑：.
複製代碼

2). 是否分離source和build目錄（輸入y,選擇分離，n:不分離(默認)）

佈置用於保存 Sphinx 輸出的構建目錄，有兩種選擇。
一是在根路徑下建立「_build」目錄，二是在根路徑下建立「source」
和「build」兩個獨立的目錄。
> 獨立的源文件和構建目錄（y/n） [n]: 

複製代碼

3). 輸入項目名稱和做者

項目名稱會出如今文檔的許多地方。
> 項目名稱: Lang-Shell
> 做者名稱: Duoli
> 項目發行版本 []: 1.0.0
複製代碼

4). 文檔語言（回車，默認便可）

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
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> 項目語種 [en]: zh
複製代碼

5). 完成設定

建立文件 ./conf.py。
建立文件 ./index.rst。
建立文件 ./Makefile。
建立文件 ./make.bat。

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

你如今能夠填寫主文檔文件 ./index.rst 並建立其餘文檔源文件了。 用 Makefile 構建文檔，像這樣：
 make builder
此處的「builder」是支持的構建器名，好比 html、latex 或 linkcheck。
複製代碼

解釋1: ，整個設置過程包括

1. 是否分離源文件目錄 source 和生成文件目錄 build，默認否；
2. 項目名稱, 項目做者, 項目版本，默認爲空；
3. 項目語言，默認爲 en, 能夠設置爲 zh；

解釋2，項目目錄文件結構以下

sphinx-doc
├── Makefile
├── build
├── make.bat
├── _static
├── _templates
├── conf.py
└── index.rst
複製代碼

其中：

• Makefile：能夠看做是一個包含指令的文件，在使用 make 命令時，可使用這些指令來構建文檔輸出。
• build：生成的文件的輸出目錄。
• make.bat：Windows 用命令行。
• _static：靜態文件目錄，好比圖片等。
• _templates：模板目錄。
• conf.py：存放 Sphinx 的配置，包括在 sphinx-quickstart 時選中的那些值，能夠自行定義其餘的值。
• index.rst：文檔項目起始文件。

接下來看看默認生成的內容：

$ make html

正在運行 Sphinx v2.3.1
正在加載翻譯 [zh]... 完成
製做輸出目錄... 完成
構建 [mo]： 0 個 po 文件的目標文件已過時
構建 [html]： 1 個源文件的目標文件已過時
更新環境: [新配置] 已添加 1，0 已更改，0 已移除
閱讀源... [100%] index                                                                                                                                     
查找當前已過時的文件... 沒有找到
pickling環境... 完成
檢查一致性... 完成
準備文件... 完成
寫入輸出... [100%] index                                                                                                                                    
generating indices...  genindex完成
writing additional pages...  search完成
複製靜態文件... ... 完成
copying extra files... 完成
dumping search index in Chinese (code: zh)... 完成
dumping object inventory... 完成
構建 成功.

HTML 頁面保存在 _build/html 目錄。
複製代碼

而後直接在瀏覽器中打開 build/html/index.html 這個文件。

更換主題, 支持 MarkDown 解析

安裝擴展

# support markdown
$ pip3 install --upgrade recommonmark

# theme
$ pip3 install sphinx_rtd_theme
# 暗黑系的主題
$ pip3 install msmb_theme
複製代碼

默認風格爲 alabaster，能夠改爲 ReadTheDocs 的風格： sphinx_rtd_theme。

conf.py

# readthedoc 風格的主題
html_theme = 'sphinx_rtd_theme'

# 擴展, 解析markdown
extensions = [
    'sphinx.ext.autodoc',
    'recommonmark',
]
複製代碼

生成文檔

在Sphinx項目所在的文件夾路徑下運行下列命令生成文檔：

make html
複製代碼

生成後的文檔位於build/html文件夾內，用瀏覽器打開index.html便可看到生成後的文檔。

加入新文檔

咱們以如下文檔爲例：

demo.rst

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo``
gives you super user powers!

複製代碼

修改 index.rst 爲:

Welcome to 一本書's documentation! ================================== .. toctree:: :maxdepth: 2 :caption: 目錄: demo.rst Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search` 複製代碼

從新編譯，這時文檔已經改變。

在線託管

ReadTheDocs 但是直接用於託管 sphinx 生成的網頁文檔。 將以前的文檔用 Git 管理，並推送到 Github，而後在 ReadTheDocs 中 Import a Project 便可。

另外，能夠設置自定義域名：

1. 在域名管理中添加 DNS 的 CNAME 記錄到 readthedocs.io，好比 onebook.qiwihui.com
2. 在項目的 Admin -> Domains 中設置上一步添加的域名，開啓 HTTPS，保存便可。

過程很簡單。

遇到的問題:

Vscode 支持實時預覽

打開 命令面板 輸入 python:select interpreter

選擇相應的便可, 若是你是 python3 來進行驅動的, 選擇合適的 python3 路徑

點擊右上角的 預覽便可

`

字體

使用 fc-list 來獲取字體信息，修改相應字體設置便可。

$ brew install fontconfig
$ fc-list :lang=zh
複製代碼

參考

簡單過了一下整個文檔的流程，整體來講，Sphinx很是適合用來編寫項目文檔，reStructuredText 比起 Markdown 也有太多的優點，值得推薦。

• 使用 Sphinx 撰寫技術文檔並生成 PDF 總結