利用 Sphinx 模組建立 HTML 說明文件

Sphinx

透過 pip 安裝 Python 的 Sphinx 模組。

$sudo pip3 install sphinx -U

接著建立一個預定存放文章的資料夾，並在此處用終端機建立 Sphinx 專案。

$sphinx-quickstart

這時會開始做專案設定，中括號的選項為預設值，大略如下所示。

Root path for the documentation [.]:

文件的根目錄。
Separate source and build directories (y/n) [n]: y

是否分開原始碼和建置目錄，這裡做分開比較好查看內容。
Name prefix for templates and static dir [_]:

templates 和 static 資料夾的前綴符號。
Author name(s): 作者

設定作者名字。
Project version [] / Project release []:

此專案的套件版本和發行版本。
Project language [en]: zh_TW

專案語系，會影響網站中「目錄」、「本頁」、「快速搜尋」字樣的顯示語言。
Source file suffix [.rst]:

支援原始碼的副檔名，在未安裝附加套件前，Sphinx 只會轉換 reStructuredText (rST) 的語法，之後可以增加 Markdown。
Name of your master document (without suffix) [index]:

首頁的檔案名稱，不包含副檔名，預設轉換後對應「index.html」。如果上面的副檔名維持預設的 .rst，會比較好轉換。
Do you want to use the epub builder (y/n) [n]:

增加 epub 電子書格式的支援。
Please indicate if you want to use one of the following Sphinx extensions:

以下都是 Sphinx 擴充功能的開關，不過若是以後要啟用，也可以直接修改 conf.py 文件變更設定。
- autodoc
- doctest
- intersphinx
- todo
- coverage
- imgmath / mathjax（擇一）
- ifconfig
- viewcode
- githubpages
Create Makefile? (y/n) [y]:

生成 Makefile 以便直接轉檔。
Create Windows command file? (y/n) [y]: n

若 Windows 平台沒裝 GNU 工具，可以透過批次檔轉檔。

Makefile

接下來，修改專案根目錄中的 Makefile，將 SPHINXBUILD 這個參數的值改成 sphinx-build，以解決在 Ubuntu 平台會呼叫成 Python 2 的問題。

Makefile 中也能設定輸入輸出的目錄。

增加 Markdown 支援

上述提及 Sphinx 沒有 Markdown 語法的支援，因此必須額外增加一個模組幫忙解析。

安裝另一個 Python 模組 recommonmark。

$sudo pip3 install recommonmark

編輯 source 目錄下的 conf.py 文件，這裡是紀錄設定的腳本檔案。

找到關於 source_suffix 的設定，改成如下：

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
from recommonmark.parser import CommonMarkParser
source_parsers = {
    '.md': CommonMarkParser,
}
source_suffix = ['.rst', '.md']

這樣就同時支援 reStructuredText 和 Markdown 語法了。

index 目錄

預設的 index 目錄為 reStructuredText 語法，這邊注意如果大小標題的底線沒有超出標題文字長度（全形字元為 2 格），轉換時會發生 Title underline is short 警告，甚至可能會跳過本章的標題，造成目錄空白。

其中包含章節的結構樹如下：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

其中 maxdepth 為目錄顯示最多的層級數；caption 為目錄上方的文字顯示。

可以添加文件名稱到底下，讓 Sphinx 排序不同檔案的章節順序，如下：

.. toctree::
   :maxdepth: 2
   :caption: 目錄:

   setup
   environment

這裡添加檔名即可，只要是支援的副檔名即可。

編出 HTML

接下來，透過 Makefile 生成 HTML 文件，這部份也類似 Pandoc 的流程。

$make html

接著進入 build 資料夾，用網頁瀏覽器開啟 index.html 檢視成果。

Sphinx 樣板

Sphinx

Makefile

增加 Markdown 支援

index 目錄

編出 HTML

Comments