本部落格已搬遷, 3秒後跳轉...

Python:Sphinx ＆ ReadTheDocs | Laplace's Lab

Python:Sphinx ＆ ReadTheDocs

| |

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

Sphinx

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

官方入門指南：Sphinx Quick Start

  1. 安裝：

    1
    $ pip install Sphinx

  2. 快速啟用：
    首先在文件的根目錄建立doc、src兩個資料夾，分別用來放建置文件和原始碼。Sphinx內建sphinx-quickstart腳本，可引導使用者快速完成基本設定：

    1
    2
    $ cd doc
    $ sphinx-quickstart

    這裡選擇獨立的原始碼和建置目錄⬇︎

    接著腳本會引導使用者設定文件名稱、版本號、作者等資訊，設定完成後的目錄結構：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    .
    ├── doc
    │   ├── Makefile
    │   ├── build
    │   ├── make.bat
    │   └── source
    │       ├── _static
    │       ├── _templates
    │       ├── conf.py
    │       └── index.rst
    └── src

    從上面的目錄結構可以看到，doc目錄下有自動建置的指令檔，source目錄中則是文件相關的資源檔，包含靜態檔案、設定檔conf.py以及首頁index.rst。

  3. conf.py基本設定：

    • 原始碼路徑：

      1
      2
      3
      4
      5
      6
      7
      8
      9
      # -- 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然後文件建置失敗😅

    • 一般設定

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

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

    • 擴充功能

      1
      2
      3
      4
      # 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']

    • 佈景主題

      1
      2
      3
      4
      # 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

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

    1
    2
    3
    4
    5
    .. toctree::
        :maxdepth: 2
        :caption: Contents:

        mod_a

    *注意空格、縮排以及不需要寫出.rst檔名後綴

    如此在生成文件的時候，首頁目錄就會有mod_a這個頁面，而mod_a頁面內容就在mod_a.rst檔案中撰寫、定義。

  5. autodoc：
    語法參考：sphinx.ext.autodoc

    簡單舉例，假設上述的mod_a.rst對應到原始碼src/proj/mod_a.py這個模組，那麼mod_a.py可能定義了一些類別或方法，則mod_a.rst的內容除了標題和一些說明文字，autodoc的設定應該長這樣：

    1
    2
    .. automodule:: proj.mod_a
        :members:

    如此audodoc便會自動將模組中的成員引入mod_a.rst頁面，包含以reStructuredText語法所撰寫的註解！例如：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    class a():

        """
        write reStructuredText here
        """

        def __init__(self):
            """
            write reStructuredText here
            """
            pass

  6. make：
    當上述的文件內容都撰寫好了，就可以使用自動建置指令來生成文件：

    1
    2
    $ make clean  # Delete the build cache before building documents
    $ make html

    建置完成的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/

0%