最好将文档作为开发过程的一部分. Sphinx 加上 Tox, 让文档可以轻松书写, 并且外观漂亮.
Python 代码可以在源码中包含文档. 这种方式默认依靠 docstring, 它以三引号格式定义. 虽然文档的价值是很大的, 但是没有充足的文档的代码还是很常见. 让我们演练一个场景, 了解出色的文档的强大功能.
经历了太多在白板技术面试上要求你实现斐波那契数列, 你已经受够了. 你回家用 Python 写了一个可重用的斐波那契计算器, 使用浮点技巧来实现 O(1) 复杂度.
代码很简单:
- # 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)
- (该斐波那契数列是四舍五入到最接近的整数的几何序列, 这是我最喜欢的鲜为人知的数学事实之一.)
作为一个好人, 你可以将代码开源, 并将它放在 PyPI https://pypi.org/ 上. setup.py 文件很简单:
- import setuptools
- setuptools.setup(
- name='fib',
- version='2019.1.0',
- description='Fibonacci',
- py_modules=["fib"],
- )
但是, 没有文档的代码是没有用的. 因此, 你可以向函数添加 docstring. 我最喜欢的 docstring 样式之一是 "Google" 样式. 标记很轻量, 当它放在源代码中时很好.
- 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
- """
- # ...
但是函数的文档只是成功的一半. 普通文档对于情境化代码用法很重要. 在这种情况下, 情景是恼人的技术面试.
有一种添加更多文档的方式, 专业 Python 人的方式通常是在 docs/ 添加 rst 文件( reStructuredText http://docutils.sourceforge.net/rst.html 的缩写). 因此 docs/index.rst 文件最终看起来像这样:
- 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:
我们完成了, 对吧? 我们已经将文本放在了文件中. 人们应该会看的.
使 Python 文档更漂亮
为了使你的文档看起来更漂亮, 你可以利用 Sphinx http://www.sphinx-doc.org/en/master/ , 它旨在制作漂亮的 Python 文档. 这三个 Sphinx 扩展特别有用:
Sphinx.ext.autodoc: 从模块内部获取文档
Sphinx.ext.napoleon: 支持 Google 样式的 docstring
Sphinx.ext.viewcode: 将 ReStructured Text 源码与生成的文档打包在一起
为了告诉 Sphinx 该生成什么以及如何生成, 我们在 docs/conf.py 中配置一个辅助文件:
- extensions = [
- 'sphinx.ext.autodoc',
- 'sphinx.ext.napoleon',
- 'sphinx.ext.viewcode',
- ]
- # 该入口点的名称, 没有 .rst 扩展名.
- # 惯例该名称是 index
- master_doc = "index"
- # 这些值全部用在生成的文档当中.
- # 通常, 发布 (release) 与版本 (version) 是一样的,
- # 但是有时候我们会有带有 rc 标签的发布.
- project = "Fib"
- copyright = "2019, Moshe Zadka"
- author = "Moshe Zadka"
- version = release = "2019.1.0"
此文件使我们可以使用所需的所有元数据来发布代码, 并注意扩展名(上面的注释说明了方式). 最后, 要确保生成我们想要的文档, 请使用 Tox https://tox.readthedocs.io/en/latest/ 管理虚拟环境以确保我们顺利生成文档:
- [tox]
- # 默认情况下,`.tox` 是该目录.
- # 将其放在非点文件中可以从
- # 文件管理器或浏览器的
- # 打开对话框中打开生成的文档,
- # 这些对话框有时会隐藏点文件.
- toxworkdir = {toxinidir}/build/tox
- [testenv:docs]
- # 从 `docs` 目录内运行 `sphinx`,
- # 以确保它不会拾取任何可能进入顶层目录下的
- # 虚拟环境或 `build/` 目录下的其他工件的杂散文件.
- changedir = docs
- # 唯一的依赖关系是 `sphinx`.
- # 如果我们使用的是单独打包的扩展程序,
- # 我们将在此处指定它们.
- # 更好的做法是指定特定版本的 Sphinx.
- deps =
- Sphinx
- # 这是用于生成 HTML 的 `sphinx` 命令.
- # 在其他情况下, 我们可能想生成 PDF 或电子书.
- commands =
- Sphinx-build -W -b HTML -d {envtmpdir}/doctrees . {envtmpdir}/HTML
- # 我们使用 Python 3.7.
- # Tox 有时会根据 testenv 的名称尝试自动检测它,
- # 但是 `docs` 没有给出有用的线索, 因此我们必须明确它.
- basepython = python3.7
现在, 无论何时运行 Tox, 它都会为你的 Python 代码生成漂亮的文档.
在 Python 中写文档很好
作为 Python 开发人员, 我们可以使用的工具链很棒. 我们可以从 docstring 开始, 添加 .rst 文件, 然后添加 Sphinx 和 Tox 来为用户美化结果.
来源: http://developer.51cto.com/art/201911/607005.htm