|
|
51CTO旗下网站
|
|
移动端

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

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

作者:Moshe Zadka来源:Linux中国|2019-11-29 20:31

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

最好将文档作为开发过程的一部分。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 来为用户美化结果。

【责任编辑:庞桂玉 TEL:(010)68476606】

点赞 0
分享:
大家都在看
猜你喜欢

订阅专栏+更多

骨干网与数据中心建设案例

骨干网与数据中心建设案例

高级网工必会
共20章 | 捷哥CCIE

403人订阅学习

中间件安全防护攻略

中间件安全防护攻略

4类安全防护
共4章 | hack_man

151人订阅学习

CentOS 8 全新学习术

CentOS 8 全新学习术

CentOS 8 正式发布
共16章 | UbuntuServer

291人订阅学习

读 书 +更多

JavaScript核心技术

它从最简单的地方入手,不仅讲述了JavaScript的基础知识,还讲述了JavsScript如何操作CSS、DOM等Ajax基础技术。而关于跨浏览器兼容问题的解...

订阅51CTO邮刊

点击这里查看样刊

订阅51CTO邮刊

51CTO服务号

51CTO官微