最好將文件作為開發過程的一部分。Sphinx 加上 Tox,讓文件可以輕鬆書寫,並且外觀漂亮。
Python 程式碼可以在原始碼中包含文件。這種方式預設依靠 docstring,它以三引號格式定義。雖然文件的價值是很大的,但是沒有充足的文件的程式碼還是很常見。讓我們演練一個場景,了解出色的文件的強大功能。
經歷了太多在白板技術面試上要求你實現斐波那契數列,你已經受夠了。你回家用 Python 寫了一個可重用的斐波那契計算器,使用浮點技巧來實現 O(1)
複雜度。
程式碼很簡單:
# fib.pyimport math_SQRT_5 = math.sqrt(5)_PHI = (1 + _SQRT_5) / 2def approx_fib(n): return round(_PHI**(n+1) / _SQRT_5)
(該斐波那契數列是四捨五入到最接近的整數的幾何序列,這是我最喜歡的鮮為人知的數學事實之一。)
作為一個好人,你可以將程式碼開源,並將它放在 PyPI 上。setup.py
檔案很簡單:
import setuptoolssetuptools.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 implementthe 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:
我們完成了,對吧?我們已經將文字放在了檔案中。人們應該會看的。
為了使你的文件看起來更漂亮,你可以利用 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 擴充套件名。# 慣例該名稱是 indexmaster_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 開發人員,我們可以使用的工具鏈很棒。我們可以從 docstring 開始,新增 .rst 檔案,然後新增 Sphinx 和 Tox 來為使用者美化結果。
你對好的文件有何評價?你還有其他喜歡的方式麼?請在評論中分享它們!