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

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

[[284181]]

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

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

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

代码很简单:

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

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

作为一个好人,你可以将代码开源,并将它放在 PyPI 上。setup.py 文件很简单:

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

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

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

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

有一种添加更多文档的方式,专业 Python 人的方式通常是在 docs/ 添加 rst 文件( reStructuredText 的缩写)。因此 docs/index.rst 文件最终看起来像这样:

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

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

使 Python 文档更漂亮

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

  • sphinx.ext.autodoc:从模块内部获取文档
  • sphinx.ext.napoleon:支持 Google 样式的 docstring
  • sphinx.ext.viewcode:将 ReStructured Text 源码与生成的文档打包在一起

为了告诉 Sphinx 该生成什么以及如何生成,我们在 docs/conf.py 中配置一个辅助文件:

  1. extensions = [
  2. 'sphinx.ext.autodoc',
  3. 'sphinx.ext.napoleon',
  4. 'sphinx.ext.viewcode',
  5. ]
  6. # 该入口点的名称,没有 .rst 扩展名。
  7. # 惯例该名称是 index
  8. master_doc = "index"
  9. # 这些值全部用在生成的文档当中。
  10. # 通常,发布(release)与版本(version)是一样的,
  11. # 但是有时候我们会有带有 rc 标签的发布。
  12. project = "Fib"
  13. copyright = "2019, Moshe Zadka"
  14. author = "Moshe Zadka"
  15. version = release = "2019.1.0"

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

  1. [tox]
  2. # 默认情况下,`.tox` 是该目录。
  3. # 将其放在非点文件中可以从
  4. # 文件管理器或浏览器的
  5. # 打开对话框中打开生成的文档,
  6. # 这些对话框有时会隐藏点文件。
  7. toxworkdir = {toxinidir}/build/tox
  8.  
  9. [testenv:docs]
  10. # `docs` 目录内运行 `sphinx`
  11. # 以确保它不会拾取任何可能进入顶层目录下的
  12. # 虚拟环境或 `build/` 目录下的其他工件的杂散文件。
  13. changedir = docs
  14. # 唯一的依赖关系是 `sphinx`
  15. # 如果我们使用的是单独打包的扩展程序,
  16. # 我们将在此处指定它们。
  17. # 更好的做法是指定特定版本的 sphinx
  18. deps =
  19. sphinx
  20. # 这是用于生成 HTML `sphinx` 命令。
  21. # 在其他情况下,我们可能想生成 PDF 或电子书。
  22. commands =
  23. sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
  24. # 我们使用 Python 3.7
  25. # Tox 有时会根据 testenv 的名称尝试自动检测它,
  26. # 但是 `docs` 没有给出有用的线索,因此我们必须明确它。
  27. basepython = python3.7

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

在 Python 中写文档很好

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

责任编辑:庞桂玉 来源: Linux中国
相关推荐

2024-01-01 13:27:44

pydoc工具代码

2012-07-10 01:34:27

代码优化代码程序员

2011-05-25 17:17:54

前端开发

2021-09-08 08:34:37

Go 文档Goland

2012-02-08 16:19:09

ibmdw

2012-02-14 12:50:13

ibmdw

2022-08-03 11:24:10

WindowsPython代码

2022-09-08 09:39:03

PythonOCR代码

2022-12-12 12:04:59

ChatGPT代码软件

2015-11-19 16:22:58

产品经理需求文档

2023-02-26 10:16:19

JavaPDF文档

2015-02-28 09:35:01

iOSpython

2020-09-23 17:16:52

Python技术工具

2023-03-10 13:38:00

Python文档扫描器

2021-04-25 15:17:29

代码软件程序员

2011-03-04 10:47:06

Nagios监控Sphinx

2020-01-14 15:03:27

Python代码编程语言

2010-06-10 10:32:35

openSUSE使用教

2018-12-19 17:20:17

2020-02-19 13:11:52

阿里 AI 代码
点赞
收藏

51CTO技术栈公众号