如何使用 Sphinx 給 Python 程式碼寫文件

最好將文件作為開發過程的一部分。Sphinx 加上 Tox，讓文件可以輕鬆書寫，並且外觀漂亮。

Python 程式碼可以在原始碼中包含文件。這種方式預設依靠 docstring，它以三引號格式定義。雖然文件的價值是很大的，但是沒有充足的文件的程式碼還是很常見。讓我們演練一個場景，瞭解出色的文件的強大功能。

經歷了太多在白板技術面試上要求你實現斐波那契數列，你已經受夠了。你回家用 Python 寫了一個可重用的斐波那契計算器，使用浮點技巧來實現 O(1) 複雜度。

程式碼很簡單：

# fib.py
import math

_SQRT_5 = math.sqrt(5)
_PHI = (1 + _SQRT_5) / 2

def approx_fib(n):
    return round(_PHI**(n+1) / _SQRT_5)

（該斐波那契數列是四捨五入到最接近的整數的幾何序列，這是我最喜歡的鮮為人知的數學事實之一。）

作為一個好人，你可以將程式碼開源，並將它放在 PyPI 上。setup.py 檔案很簡單：

import setuptools

setuptools.setup(
    name='fib',
    version='2019.1.0',
    description='Fibonacci',
    py_modules=["fib"],
)

但是，沒有文件的程式碼是沒有用的。因此，你可以向函式新增 docstring。我最喜歡的 docstring 樣式之一是 “Google” 樣式。標記很輕量，當它放在原始碼中時很好。

def approx_fib(n):
    """
    Approximate Fibonacci sequence

    Args:
        n (int): The place in Fibonacci sequence to approximate

    Returns:
        float: The approximate value in Fibonacci sequence
    """
    # ...

但是函式的文件只是成功的一半。普通文件對於情境化程式碼用法很重要。在這種情況下，情景是惱人的技術面試。

有一種新增更多文件的方式，專業 Python 人的方式通常是在 docs/ 新增 rst 檔案（ reStructuredText 的縮寫）。因此 docs/index.rst 檔案最終看起來像這樣：

Fibonacci
=========

Are you annoyed at tech interviewers asking you to implement
the Fibonacci sequence?
Do you want to have some fun with them?
A simple
:code:`pip install fib`
is all it takes to tell them to,
um,
fib off.

.. automodule:: fib
   :members:

我們完成了，對吧？我們已經將文字放在了檔案中。人們應該會看的。

使 Python 文件更漂亮

為了使你的文件看起來更漂亮，你可以利用 Sphinx，它旨在製作漂亮的 Python 文件。這三個 Sphinx 擴充套件特別有用：

• sphinx.ext.autodoc：從模組內部獲取文件
• sphinx.ext.napoleon：支援 Google 樣式的 docstring
• sphinx.ext.viewcode：將 ReStructured Text 原始碼與生成的文件打包在一起

為了告訴 Sphinx 該生成什麼以及如何生成，我們在 docs/conf.py 中配置一個輔助檔案：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
]
# 該入口點的名稱，沒有 .rst 副檔名。
# 慣例該名稱是 index
master_doc = "index"
# 這些值全部用在生成的文件當中。
# 通常，釋出（release）與版本（version）是一樣的，
# 但是有時候我們會有帶有 rc 標籤的釋出。
project = "Fib"
copyright = "2019, Moshe Zadka"
author = "Moshe Zadka"
version = release = "2019.1.0"

此檔案使我們可以使用所需的所有後設資料來發布程式碼，並注意副檔名（上面的註釋說明了方式）。最後，要確保生成我們想要的文件，請使用 Tox 管理虛擬環境以確保我們順利生成文件：

[tox]
# 預設情況下，`.tox` 是該目錄。
# 將其放在非點檔案中可以從
# 檔案管理器或瀏覽器的
# 開啟對話方塊中開啟生成的文件，
# 這些對話方塊有時會隱藏點檔案。
toxworkdir = {toxinidir}/build/tox

[testenv:docs]
# 從 `docs` 目錄內執行 `sphinx`，
# 以確保它不會拾取任何可能進入頂層目錄下的
# 虛擬環境或 `build/` 目錄下的其他工件的雜散檔案。
changedir = docs
# 唯一的依賴關係是 `sphinx`。
# 如果我們使用的是單獨打包的擴充套件程式，
# 我們將在此處指定它們。
# 更好的做法是指定特定版本的 sphinx。
deps =
    sphinx
# 這是用於生成 HTML 的 `sphinx` 命令。
# 在其他情況下，我們可能想生成 PDF 或電子書。
commands =
    sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
# 我們使用 Python 3.7。
# Tox 有時會根據 testenv 的名稱嘗試自動檢測它，
# 但是 `docs` 沒有給出有用的線索，因此我們必須明確它。
basepython = python3.7

現在，無論何時執行 Tox，它都會為你的 Python 程式碼生成漂亮的文件。

在 Python 中寫文件很好

作為 Python 開發人員，我們可以使用的工具鏈很棒。我們可以從 docstring 開始，新增 .rst 檔案，然後新增 Sphinx 和 Tox 來為使用者美化結果。

你對好的文件有何評價？你還有其他喜歡的方式麼？請在評論中分享它們！

---

via: https://opensource.com/article/19/11/document-python-sphinx

作者：Moshe Zadka 選題：lujun9972 譯者：geekpi 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

訂閱“Linux 中國”官方小程式來檢視