Python 代码可以在其源代码中包含文档。默认方法依赖于文档字符串，文档字符串以三引号格式定义。虽然文档的价值已得到充分... 证明，但似乎文档记录不足的情况太常见了。让我们来看一个关于出色文档的力量的场景。
在经历了太多在白板上进行的、要求你实现斐波那契数列的技术面试之后，你已经受够了。你回家用 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 上。setup.py 文件非常简单
import setuptools
setuptools.setup(
name='fib',
version='2019.1.0',
description='Fibonacci',
py_modules=["fib"],
)但是，没有文档的代码是无用的。因此，你向函数添加了文档字符串。我最喜欢的文档字符串风格之一是 “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
"""
# ...但是，函数的文档只是战斗的一半。散文文档对于情境化代码用法非常重要。在本例中，上下文是令人讨厌的技术面试。
有一个选项可以添加更多文档，而 Pythonic 模式是使用 rst 文件（reStructuredText 的缩写），通常添加到 docs/ 目录下。因此，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，它旨在制作漂亮的 Python 文档。特别是，以下三个 Sphinx 扩展很有用
- sphinx.ext.autodoc：从模块内部抓取文档
- sphinx.ext.napoleon：支持 Google 风格的文档字符串
- sphinx.ext.viewcode：将 ReStructured Text 源文件与生成的文档打包在一起
为了告诉 Sphinx 生成什么以及如何生成，我们在 docs/conf.py 中配置一个辅助文件
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.viewcode',
]
# The name of the entry point, without the ".rst" extension.
# By convention this will be "index"
master_doc = "index"
# This values are all used in the generated documentation.
# Usually, the release and version are the same,
# but sometimes we want to have the release have an "rc" tag.
project = "Fib"
copyright = "2019, Moshe Zadka"
author = "Moshe Zadka"
version = release = "2019.1.0"此文件允许我们发布包含所有我们想要的元数据的代码，并注明我们的扩展（上面的注释解释了如何操作）。最后，为了准确记录我们希望如何生成文档，请使用 Tox 来管理虚拟环境，以确保我们顺利生成文档
[tox]
# By default, .tox is the directory.
# Putting it in a non-dot file allows opening the generated
# documentation from file managers or browser open dialogs
# that will sometimes hide dot files.
toxworkdir = {toxinidir}/build/tox
[testenv:docs]
# Running sphinx from inside the "docs" directory
# ensures it will not pick up any stray files that might
# get into a virtual environment under the top-level directory
# or other artifacts under build/
changedir = docs
# The only dependency is sphinx
# If we were using extensions packaged separately,
# we would specify them here.
# A better practice is to specify a specific version of sphinx.
deps =
sphinx
# This is the sphinx command to generate HTML.
# In other circumstances, we might want to generate a PDF or an ebook
commands =
sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
# We use Python 3.7. Tox sometimes tries to autodetect it based on the name of
# the testenv, but "docs" does not give useful clues so we have to be explicit.
basepython = python3.7现在，每当你运行 Tox 时，它都会为你的 Python 代码生成漂亮的文档。
Python 中的文档非常出色
作为一名 Python 开发者，我们可用的工具链非常棒。我们可以从文档字符串开始，添加 .rst 文件，然后添加 Sphinx 和 Tox 来美化用户的结果。
你欣赏好的文档的哪些方面？你还有其他喜欢的技巧吗？在评论中分享它们！
评论已关闭。