最好将文档作为开发过程的一部分。Sphinx 加上 Tox,让文档可以轻松书写,并且外观漂亮。
Python 代码可以在源码中包含文档。这种方式默认依靠 docstring,它以三引号格式定义。虽然文档的价值是很大的,但是没有充足的文档的代码还是很常见。让我们演练一个场景,了解出色的文档的强大功能。
经历了太多在白板技术面试上要求你实现斐波那契数列,你已经受够了。你回家用 Python 写了一个可重用的斐波那契计算器,使用浮点技巧来实现 O(1) 复杂度。
代码很简单:
#fib.py
importmath
_SQRT_5=math.sqrt(5)
_PHI=(1+_SQRT_5)/2
defapprox_fib(n):
returnround(_PHI**(n+1)/_SQRT_5)
(该斐波那契数列是四舍五入到最接近的整数的几何序列,这是我最喜欢的鲜为人知的数学事实之一。)
作为一个好人,你可以将代码开源,并将它放在 PyPI 上。setup.py 文件很简单:
importsetuptools
setuptools.setup(
name='fib',
version='2019.1.0',
description='Fibonacci',
py_modules=["fib"],
)
但是,没有文档的代码是没有用的。因此,你可以向函数添加 docstring。我最喜欢的 docstring 样式之一是 “Google” 样式。标记很轻量,当它放在源代码中时很好。
defapprox_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 的缩写)。因此 docs/index.rst 文件最终看起来像这样:
Fibonacci
=========
Areyou annoyed at tech interviewers asking you to implement
theFibonaccisequence?
Doyou want to have some funwiththem?
A simple
:code:`pip install fib`
isall it takes to tell them to,
um,
fib off.
..automodule::fib
:members:
我们完成了,对吧?我们已经将文本放在了文件中。人们应该会看的。
使 Python 文档更漂亮
为了使你的文档看起来更漂亮,你可以利用 Sphinx,它旨在制作漂亮的 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 管理虚拟环境以确保我们顺利生成文档:
[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
#我们使用Python3.7。
#Tox有时会根据testenv的名称尝试自动检测它,
#但是`docs`没有给出有用的线索,因此我们必须明确它。
basepython=python3.7
现在,无论何时运行 Tox,它都会为你的 Python 代码生成漂亮的文档。
在 Python 中写文档很好
作为 Python 开发人员,我们可以使用的工具链很棒。我们可以从 docstring 开始,添加 .rst 文件,然后添加 Sphinx 和 Tox 来为用户美化结果。
【责任编辑:庞桂玉 TEL:(010)68476606】
点赞 0