建站
咨詢(xún)
售后
建站咨詢(xún)
新聞中心
Sphinx 是由 Georg Brandl 編寫(xiě)的工具，可輕松為 Python 項(xiàng)目（或由多個(gè) reStructuredText 源組成的其他文檔）創(chuàng)建智能且美觀的文檔。它最初是為新的 Python 文檔創(chuàng)建的，具有用于Python項(xiàng)目文檔的出色功能，但同時(shí)也支持C / C ++，并且計(jì)劃了更多的語(yǔ)言。
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 寫(xiě)了一個(gè)可重用的斐波那契計(jì)算器，使用浮點(diǎn)技巧來(lái)實(shí)現(xiàn) O(1) 復(fù)雜度。 代碼很簡(jiǎn)單：
# 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)
（該斐波那契數(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ù)面試。 有一種添加更多文檔的方式，專(zhuān)業(yè) Python 人的方式通常是在 docs/ 添加 rst 文件（ reStructuredText 的縮寫(xiě)）。因此 docs/index.rst 文件最終看起來(lái)像這樣：
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:
我們完成了，對(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)的名稱(chēng)，沒(méi)有 .rst 擴(kuò)展名。
# 慣例該名稱(chēng)是 index
master_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ì)話(huà)框中打開(kāi)生成的文檔，
# 這些對(duì)話(huà)框有時(shí)會(huì)隱藏點(diǎn)文件。
toxworkdir = {toxinidir}/build/tox
[testenv:docs]
# 從 `docs` 目錄內(nèi)運(yùn)行 `sphinx`，
# 以確保它不會(huì)拾取任何可能進(jìn)入頂層目錄下的
# 虛擬環(huán)境或 `build/` 目錄下的其他工件的雜散文件。
changedir = docs
# 唯一的依賴(lài)關(guān)系是 `sphinx`。
# 如果我們使用的是單獨(dú)打包的擴(kuò)展程序，
# 我們將在此處指定它們。
# 更好的做法是指定特定版本的 sphinx。
deps =
sphinx
# 這是用于生成 HTML 的 `sphinx` 命令。
# 在其他情況下，我們可能想生成 PDF 或電子書(shū)。
commands =
sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
# 我們使用 Python 3.7。
# Tox 有時(shí)會(huì)根據(jù) testenv 的名稱(chēng)嘗試自動(dòng)檢測(cè)它，
# 但是 `docs` 沒(méi)有給出有用的線(xiàn)索，因此我們必須明確它。
basepython = python3.7
現(xiàn)在，無(wú)論何時(shí)運(yùn)行 Tox，它都會(huì)為你的 Python 代碼生成漂亮的文檔。 在 Python 中寫(xiě)文檔很好 作為 Python 開(kāi)發(fā)人員，我們可以使用的工具鏈很棒。我們可以從 docstring 開(kāi)始，添加 .rst 文件，然后添加 Sphinx 和 Tox 來(lái)為用戶(hù)美化結(jié)果。
網(wǎng)站標(biāo)題：使用Sphinx創(chuàng)建Python代碼寫(xiě)文檔
鏈接URL：http://www.5511xx.com/article/copogjc.html
