這篇文章將為大家詳細(xì)講解有關(guān)怎么使用Sphinx給Python代碼寫文檔，小編覺(jué)得挺實(shí)用的，因此分享給大家做個(gè)參考，希望大家閱讀完這篇文章后可以有所收獲。

我們提供的服務(wù)有：成都網(wǎng)站設(shè)計(jì)、做網(wǎng)站、微信公眾號(hào)開(kāi)發(fā)、網(wǎng)站優(yōu)化、網(wǎng)站認(rèn)證、嵐山ssl等。為上千家企事業(yè)單位解決了網(wǎng)站和推廣的問(wèn)題。提供周到的售前咨詢和貼心的售后服務(wù)，是有科學(xué)管理、有技術(shù)的嵐山網(wǎng)站制作公司

Python 代碼可以在源碼中包含文檔。這種方式默認(rèn)依靠 docstring，它以三引號(hào)格式定義。雖然文檔的價(jià)值是很大的，但是沒(méi)有充足的文檔的代碼還是很常見(jiàn)。讓我們演練一個(gè)場(chǎng)景，了解出色的文檔的強(qiáng)大功能。

經(jīng)歷了太多在白板技術(shù)面試上要求你實(shí)現(xiàn)斐波那契數(shù)列，你已經(jīng)受夠了。你回家用 Python 寫了一個(gè)可重用的斐波那契計(jì)算器，使用浮點(diǎn)技巧來(lái)實(shí)現(xiàn) O(1) 復(fù)雜度。

代碼很簡(jiǎn)單：

# fib.pyimport math _SQRT_5 = math.sqrt(5)_PHI = (1 + _SQRT_5) / 2 def approx_fib(n):    return round(_PHI**(n+1) / _SQRT_5)

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

作為一個(gè)好人，你可以將代碼開(kāi)源，并將它放在 PyPI 上。setup.py 文件很簡(jiǎn)單：

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

但是，沒(méi)有文檔的代碼是沒(méi)有用的。因此，你可以向函數(shù)添加 docstring。我最喜歡的 docstring 樣式之一是 “Google” 樣式。標(biāo)記很輕量，當(dāng)它放在源代碼中時(shí)很好。

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    """    # ...

但是函數(shù)的文檔只是成功的一半。普通文檔對(duì)于情境化代碼用法很重要。在這種情況下，情景是惱人的技術(shù)面試。

有一種添加更多文檔的方式，專業(yè) Python 人的方式通常是在 docs/ 添加 rst 文件（ reStructuredText 的縮寫）。因此 docs/index.rst 文件最終看起來(lái)像這樣：

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:

我們完成了，對(duì)吧？我們已經(jīng)將文本放在了文件中。人們應(yīng)該會(huì)看的。

使 Python 文檔更漂亮

為了使你的文檔看起來(lái)更漂亮，你可以利用 Sphinx，它旨在制作漂亮的 Python 文檔。這三個(gè) Sphinx 擴(kuò)展特別有用：

• sphinx.ext.autodoc：從模塊內(nèi)部獲取文檔

• sphinx.ext.napoleon：支持 Google 樣式的 docstring

• sphinx.ext.viewcode：將 ReStructured Text 源碼與生成的文檔打包在一起

為了告訴 Sphinx 該生成什么以及如何生成，我們?cè)?docs/conf.py 中配置一個(gè)輔助文件：

extensions = [    'sphinx.ext.autodoc',    'sphinx.ext.napoleon',    'sphinx.ext.viewcode',]# 該入口點(diǎn)的名稱，沒(méi)有 .rst 擴(kuò)展名。# 慣例該名稱是 indexmaster_doc = "index"# 這些值全部用在生成的文檔當(dāng)中。# 通常，發(fā)布（release）與版本（version）是一樣的，# 但是有時(shí)候我們會(huì)有帶有 rc 標(biāo)簽的發(fā)布。project = "Fib"copyright = "2019, Moshe Zadka"author = "Moshe Zadka"version = release = "2019.1.0"

此文件使我們可以使用所需的所有元數(shù)據(jù)來(lái)發(fā)布代碼，并注意擴(kuò)展名（上面的注釋說(shuō)明了方式）。最后，要確保生成我們想要的文檔，請(qǐng)使用 Tox 管理虛擬環(huán)境以確保我們順利生成文檔：

[tox]# 默認(rèn)情況下，`.tox` 是該目錄。# 將其放在非點(diǎn)文件中可以從# 文件管理器或?yàn)g覽器的# 打開(kāi)對(duì)話框中打開(kāi)生成的文檔，# 這些對(duì)話框有時(shí)會(huì)隱藏點(diǎn)文件。toxworkdir = {toxinidir}/build/tox [testenv:docs]# 從 `docs` 目錄內(nèi)運(yùn)行 `sphinx`，# 以確保它不會(huì)拾取任何可能進(jìn)入頂層目錄下的# 虛擬環(huán)境或 `build/` 目錄下的其他工件的雜散文件。changedir = docs# 唯一的依賴關(guān)系是 `sphinx`。# 如果我們使用的是單獨(dú)打包的擴(kuò)展程序，# 我們將在此處指定它們。# 更好的做法是指定特定版本的 sphinx。deps =    sphinx# 這是用于生成 HTML 的 `sphinx` 命令。# 在其他情況下，我們可能想生成 PDF 或電子書。commands =    sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html# 我們使用 Python 3.7。# Tox 有時(shí)會(huì)根據(jù) testenv 的名稱嘗試自動(dòng)檢測(cè)它，# 但是 `docs` 沒(méi)有給出有用的線索，因此我們必須明確它。basepython = python3.7

現(xiàn)在，無(wú)論何時(shí)運(yùn)行 Tox，它都會(huì)為你的 Python 代碼生成漂亮的文檔。

在 Python 中寫文檔很好

作為 Python 開(kāi)發(fā)人員，我們可以使用的工具鏈很棒。我們可以從 docstring開(kāi)始，添加 .rst 文件，然后添加 Sphinx 和 Tox 來(lái)為用戶美化結(jié)果。

關(guān)于“怎么使用Sphinx給Python代碼寫文檔”這篇文章就分享到這里了，希望以上內(nèi)容可以對(duì)大家有一定的幫助，使各位可以學(xué)到更多知識(shí)，如果覺(jué)得文章不錯(cuò)，請(qǐng)把它分享出去讓更多的人看到。