日韩无码专区无码一级三级片|91人人爱网站中日韩无码电影|厨房大战丰满熟妇|AV高清无码在线免费观看|另类AV日韩少妇熟女|中文日本大黄一级黄色片|色情在线视频免费|亚洲成人特黄a片|黄片wwwav色图欧美|欧亚乱色一区二区三区

RELATEED CONSULTING
相關(guān)咨詢
選擇下列產(chǎn)品馬上在線溝通
服務(wù)時間：8:30-17:00
你可能遇到了下面的問題
關(guān)閉右側(cè)工具欄

新聞中心

這里有您想知道的互聯(lián)網(wǎng)營銷解決方案
如何使用Sphinx給Python代碼寫文檔

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

成都創(chuàng)新互聯(lián)是專業(yè)的井研網(wǎng)站建設(shè)公司，井研接單;提供網(wǎng)站設(shè)計制作、做網(wǎng)站,網(wǎng)頁設(shè)計,網(wǎng)站設(shè)計,建網(wǎng)站,PHP網(wǎng)站建設(shè)等專業(yè)做網(wǎng)站服務(wù);采用PHP框架,可快速的進(jìn)行井研網(wǎng)站開發(fā)網(wǎng)頁制作和功能擴(kuò)展;專業(yè)做搜索引擎喜愛的網(wǎng)站,專業(yè)的做網(wǎng)站團(tuán)隊,希望更多企業(yè)前來合作!

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

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

代碼很簡單：

 
 
 
      
  
  
  1. # fib.py
    2.   
  
  
  2. import math
    3.   
  
  
  3.  
    4.   
  
  
  4. _SQRT_5 = math.sqrt(5)
    5.   
  
  
  5. _PHI = (1 + _SQRT_5) / 2
    6.   
  
  
  6.  
    7.   
  
  
  7. def approx_fib(n):
    8.   
  
  
  8.  return round(_PHI**(n+1) / _SQRT_5)
    9.

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

作為一個好人，你可以將代碼開源，并將它放在 PyPI 上。setup.py 文件很簡單：

 
 
 
      
  
  
  1. import setuptools
    2.   
  
  
  2.  
    3.   
  
  
  3. setuptools.setup(
    4.   
  
  
  4.  name='fib',
    5.   
  
  
  5.  version='2019.1.0',
    6.   
  
  
  6.  description='Fibonacci',
    7.   
  
  
  7.  py_modules=["fib"],
    8.   
  
  
  8. )
    9.

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

 
 
 
      
  
  
  1. def approx_fib(n):
    2.   
  
  
  2.  """
    3.   
  
  
  3.  Approximate Fibonacci sequence
    4.   
  
  
  4.  
    5.   
  
  
  5.  Args:
    6.   
  
  
  6.  n (int): The place in Fibonacci sequence to approximate
    7.   
  
  
  7.  
    8.   
  
  
  8.  Returns:
    9.   
  
  
  9.  float: The approximate value in Fibonacci sequence
    10.   
  
  
  10.  """
    11.   
  
  
  11.  # ...
    12.

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

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

 
 
 
      
  
  
  1. Fibonacci
    2.   
  
  
  2. =========
    3.   
  
  
  3.  
    4.   
  
  
  4. Are you annoyed at tech interviewers asking you to implement
    5.   
  
  
  5. the Fibonacci sequence?
    6.   
  
  
  6. Do you want to have some fun with them?
    7.   
  
  
  7. A simple
    8.   
  
  
  8. :code:`pip install fib`
    9.   
  
  
  9. is all it takes to tell them to,
    10.   
  
  
  10. um,
    11.   
  
  
  11. fib off.
    12.   
  
  
  12.  
    13.   
  
  
  13. .. automodule:: fib
    14.   
  
  
  14.  :members:
    15.

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

使 Python 文檔更漂亮

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

  • sphinx.ext.autodoc：從模塊內(nèi)部獲取文檔
  • sphinx.ext.napoleon：支持 Google 樣式的 docstring
  • sphinx.ext.viewcode：將 ReStructured Text 源碼與生成的文檔打包在一起

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

 
 
 
      
  
  
  1. extensions = [
    2.   
  
  
  2.  'sphinx.ext.autodoc',
    3.   
  
  
  3.  'sphinx.ext.napoleon',
    4.   
  
  
  4.  'sphinx.ext.viewcode',
    5.   
  
  
  5. ]
    6.   
  
  
  6. # 該入口點(diǎn)的名稱，沒有 .rst 擴(kuò)展名。
    7.   
  
  
  7. # 慣例該名稱是 index
    8.   
  
  
  8. master_doc = "index"
    9.   
  
  
  9. # 這些值全部用在生成的文檔當(dāng)中。
    10.   
  
  
  10. # 通常，發(fā)布（release）與版本（version）是一樣的，
    11.   
  
  
  11. # 但是有時候我們會有帶有 rc 標(biāo)簽的發(fā)布。
    12.   
  
  
  12. project = "Fib"
    13.   
  
  
  13. copyright = "2019, Moshe Zadka"
    14.   
  
  
  14. author = "Moshe Zadka"
    15.   
  
  
  15. version = release = "2019.1.0"
    16.

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

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

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

在 Python 中寫文檔很好

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


本文標(biāo)題：如何使用Sphinx給Python代碼寫文檔
分享地址：http://m.5511xx.com/article/djoheph.html