美图齐众专注资阳网站设计 资阳网站制作 资阳网站建设
资阳网站建设公司服务热线：028-86922220

网站建设知识

十年网站开发经验 + 多家企业客户 + 靠谱的建站团队

量身定制 + 运营维护+专业推广+无忧售后，网站问题一站解决

如何使用Sphinx给Python代码写文档

最好将文档作为开发过程的一部分。Sphinx 加上 Tox，让文档可以轻松书写，并且外观漂亮。

成都创新互联是专业的井研网站建设公司，井研接单;提供网站设计制作、做网站,网页设计,网站设计,建网站,PHP网站建设等专业做网站服务;采用PHP框架,可快速的进行井研网站开发网页制作和功能扩展;专业做搜索引擎喜爱的网站,专业的做网站团队,希望更多企业前来合作!

Python 代码可以在源码中包含文档。这种方式默认依靠 docstring，它以三引号格式定义。虽然文档的价值是很大的，但是没有充足的文档的代码还是很常见。让我们演练一个场景，了解出色的文档的强大功能。

经历了太多在白板技术面试上要求你实现斐波那契数列，你已经受够了。你回家用 Python 写了一个可重用的斐波那契计算器，使用浮点技巧来实现 O(1) 复杂度。

代码很简单：

 
 
 
      
  
  
  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.

（该斐波那契数列是四舍五入到最接近的整数的几何序列，这是我最喜欢的鲜为人知的数学事实之一。）

作为一个好人，你可以将代码开源，并将它放在 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.

但是，没有文档的代码是没有用的。因此，你可以向函数添加 docstring。我最喜欢的 docstring 样式之一是 “Google” 样式。标记很轻量，当它放在源代码中时很好。

 
 
 
      
  
  
  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.

但是函数的文档只是成功的一半。普通文档对于情境化代码用法很重要。在这种情况下，情景是恼人的技术面试。

有一种添加更多文档的方式，专业 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.

我们完成了，对吧？我们已经将文本放在了文件中。人们应该会看的。

使 Python 文档更漂亮

为了使你的文档看起来更漂亮，你可以利用 Sphinx，它旨在制作漂亮的 Python 文档。这三个 Sphinx 扩展特别有用：

  • sphinx.ext.autodoc：从模块内部获取文档
  • 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. # 该入口点的名称，没有 .rst 扩展名。
    7.   
  
  
  7. # 惯例该名称是 index
    8.   
  
  
  8. master_doc = "index"
    9.   
  
  
  9. # 这些值全部用在生成的文档当中。
    10.   
  
  
  10. # 通常，发布（release）与版本（version）是一样的，
    11.   
  
  
  11. # 但是有时候我们会有带有 rc 标签的发布。
    12.   
  
  
  12. project = "Fib"
    13.   
  
  
  13. copyright = "2019, Moshe Zadka"
    14.   
  
  
  14. author = "Moshe Zadka"
    15.   
  
  
  15. version = release = "2019.1.0"
    16.

此文件使我们可以使用所需的所有元数据来发布代码，并注意扩展名（上面的注释说明了方式）。最后，要确保生成我们想要的文档，请使用 Tox 管理虚拟环境以确保我们顺利生成文档：

 
 
 
      
  
  
  1. [tox]
    2.   
  
  
  2. # 默认情况下，`.tox` 是该目录。
    3.   
  
  
  3. # 将其放在非点文件中可以从
    4.   
  
  
  4. # 文件管理器或浏览器的
    5.   
  
  
  5. # 打开对话框中打开生成的文档，
    6.   
  
  
  6. # 这些对话框有时会隐藏点文件。
    7.   
  
  
  7. toxworkdir = {toxinidir}/build/tox
    8.   
  
  
  8.  
    9.   
  
  
  9. [testenv:docs]
    10.   
  
  
  10. # 从 `docs` 目录内运行 `sphinx`，
    11.   
  
  
  11. # 以确保它不会拾取任何可能进入顶层目录下的
    12.   
  
  
  12. # 虚拟环境或 `build/` 目录下的其他工件的杂散文件。
    13.   
  
  
  13. changedir = docs
    14.   
  
  
  14. # 唯一的依赖关系是 `sphinx`。
    15.   
  
  
  15. # 如果我们使用的是单独打包的扩展程序，
    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 有时会根据 testenv 的名称尝试自动检测它，
    26.   
  
  
  26. # 但是 `docs` 没有给出有用的线索，因此我们必须明确它。
    27.   
  
  
  27. basepython = python3.7
    28.

现在，无论何时运行 Tox，它都会为你的 Python 代码生成漂亮的文档。

在 Python 中写文档很好

作为 Python 开发人员，我们可以使用的工具链很棒。我们可以从 docstring 开始，添加 .rst 文件，然后添加 Sphinx 和 Tox 来为用户美化结果。


网页题目：如何使用Sphinx给Python代码写文档
本文路径：http://zsjierui.cn/article/djoheph.html

其他资讯