最好將文檔作為開發過程的一部分。Sphinx 加上 Tox，讓文檔可以輕松書寫，并且外觀漂亮。-- Moshe Zadka

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:

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

使 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 擴展名。# 慣例該名稱是 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 中寫文檔很好

作為 Python 開發人員，我們可以使用的工具鏈很棒。我們可以從?docstring?開始，添加 .rst 文件，然后添加 Sphinx 和 Tox 來為用戶美化結果。

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

---

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

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

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

?：還在看嗎？ 《新程序員》：云原生和全面數字化實踐50位技術專家共同創作，文字、視頻、音頻交互閱讀

總結

以上是生活随笔為你收集整理的python如何读取公共盘的文档_如何使用 Sphinx 给 Python 代码写文档 | Linux 中国的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。