Python:Sphinx ＆ ReadTheDocs

當我認真想為side project寫文件的時候，於是想到了Sphinx，雖然還是對路徑設定感到有點苦惱，但自動生成文件真的很香，尤其是託管到Read The Docs還能和Github連動，只要推送更新到Github就會觸發自動建置。

Sphinx

總之Sphinx就是能自動生成文件的工具，只要在原始碼中使用reStructuredText或Markdown語法來撰寫文件內容。

安裝：
shell
```
$ pip install Sphinx
```
1
快速啟用：首先在文件的根目錄建立doc、src兩個資料夾，分別用來放建置文件和原始碼。Sphinx內建sphinx-quickstart腳本，可引導使用者快速完成基本設定：
shell
```
$ cd doc
$ sphinx-quickstart
```
1
2
這裡選擇獨立的原始碼和建置目錄⬇︎
接著腳本會引導使用者設定文件名稱、版本號、作者等資訊，設定完成後的目錄結構：
shell
```
.
├── doc
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       ├── _templates
│       ├── conf.py
│       └── index.rst
└── src
```
1
2
3
4
5
6
7
8
9
10
11
從上面的目錄結構可以看到，doc目錄下有自動建置的指令檔，source目錄中則是文件相關的資源檔，包含靜態檔案、設定檔conf.py以及首頁index.rst。

conf.py基本設定：

原始碼路徑：

python

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))

路徑不能亂設定，例如將package目錄直接設定為原始碼路徑，然後就導致各種import error然後文件建置失敗😅

一般設定

python

# -- General configuration ---------------------------------------------------
master_doc = 'index'  # main page: index.rst
autodoc_member_order = 'bysource'  # optional

如果不希望autodoc自動對member排序就設定為'bysource'。

擴充功能

python

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc']

佈景主題

python

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'  # default

更多主題：Sphinx Doc / Theming

index.rst主頁設定：打開index.rst會看到標題和toctree目錄設定，.rst也就是reStructuredText格式的文件，因此文件的每一個頁面都會有一個.rst檔，按需求自行新增。假設我有index.rst和mod_a.rst兩個頁面，那麼toctree目錄設定應該長這樣：
shell
```
.. toctree::
    :maxdepth: 2
    :caption: Contents:

    mod_a
```
1
2
3
4
5
*注意空格、縮排以及不需要寫出.rst檔名後綴
如此在生成文件的時候，首頁目錄就會有mod_a這個頁面，而mod_a頁面內容就在mod_a.rst檔案中撰寫、定義。
autodoc：語法參考：sphinx.ext.autodoc
簡單舉例，假設上述的mod_a.rst對應到原始碼src/proj/mod_a.py這個模組，那麼mod_a.py可能定義了一些類別或方法，則mod_a.rst的內容除了標題和一些說明文字，autodoc的設定應該長這樣：
shell
```
.. automodule:: proj.mod_a
    :members:
```
1
2
如此audodoc便會自動將模組中的成員引入mod_a.rst頁面，包含以reStructuredText語法所撰寫的註解！例如：
python
```
class a():

    """
    write reStructuredText here
    """

    def __init__(self):
        """
        write reStructuredText here
        """
        pass
```
1
2
3
4
5
6
7
8
9
10
11
make：當上述的文件內容都撰寫好了，就可以使用自動建置指令來生成文件：
shell
```
$ make clean  # Delete the build cache before building documents
$ make html
```
1
2
建置完成的html檔會在/doc/build目錄下。
Sphinx文件實例，供參考：laplacetw/botlegram-doc

Read The Docs

生成了文件後若打算公開發佈，可以使用Read The Docs這個基於Sphinx的免費文件託管服務，註冊帳號後，建議與版本控制服務例如Github連動，如此便可以直接從Github匯入我們的Sphinx專案來建立一個Read The Docs專案，之後只要推送更新到Github，那麼Read The Docs便會自動建置更新我們的線上文件了。

Read The Docs線上文件實例，供參考：https://botlegram.readthedocs.io/

Sphinx ​

Read The Docs ​

Sphinx

Read The Docs