如何使用 Sphinx 給 Python 代碼寫文檔
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 樣式的 docstringsphinx.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
本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive