最好将文档作为开发过程的一部分。SphinxplusTox使文档易于编写且美观。Python代码可以在源代码中包含文档。这种方法默认依赖于以三引号格式定义的文档字符串。虽然文档的价值很大，但没有足够文档的代码是很常见的。让我们通过一个场景来了解优秀文档的力量。您已经受够了要求您实现斐波那契数列的白板技术面试。你回家用Python编写一个可重用的斐波那契计算器，使用浮点技巧来实现O(1)复杂度。代码很简单：#fib.pyimportmath_SQRT_5=math.sqrt(5)_PHI=(1+_SQRT_5)/2defapprox_fib(n):returnround(_PHI**(n+1)/_SQRT_5)（fibA序列是一个四舍五入到最接近整数的几何序列，这是我最喜欢的数学鲜为人知的事实之一。）做一个好人，你可以开源代码并将其放在PyPI上。setup.py文件很简单：importsetuptoolssetuptools.setup(name='fib',version='2019.1.0',description='Fibonacci',py_modules=["fib"],)但是没有文档的代码是没有用的.因此，您可以将文档字符串添加到函数中。我最喜欢的文档字符串样式之一是“Google”样式。标记是轻量级的，当它在源代码中时很好。defapprox_fib(n):"""近似斐波那契数列Args:n(int):斐波那契数列中要近似的位置Returns:float:斐波那契数列中的近似值"""#...但是该函数的文档是只成功了一半。通用文档对于上下文化代码使用很重要。在这种情况下，场景是一个烦人的技术面试。有一种添加更多文档的方法，专业Python人员通常这样做的方法是在docs/中添加rst文件（reStructuredText的缩写）。所以docs/index.rst文件最终看起来像这样：Fibonacci=========你是否讨厌技术面试官要求你实现斐波那契数列？你想和他们一起玩吗？只需一个简单的代码：`pipinstallfib`就可以告诉他们，嗯，关闭fib...automodule::fib:members：我们完成了，对吧？我们已将文本放入文件中。人们应该关注它。让Python文档更漂亮为了让你的文档看起来更漂亮，你可以利用Sphinx，它旨在制作漂亮的Python文档。这三个Sphinx扩展特别有用：sphinx.ext.autodoc：从模块中获取文档sphinx.ext.napoleon：支持Google风格的文档字符串sphinx.ext.viewcode：将ReStructuredText源代码与生成的文档打包，以便告诉Sphinx什么生成以及如何生成，我们在docs/conf.py配置一个辅助文件：extensions=['sphinx.ext.autodoc','sphinx.ext.napoleon','sphinx.ext.viewcode',]#the入口点的名称，不带.rst扩展名。#按照约定名称是indexmaster_doc="index"#这些值都是在生成的文档中用到的。#通常，release与version相同，#但有时我们的release带有rc标签。project="Fib"copyright="2019,MosheZadka"author="MosheZadka"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或电子书。命令=sphinx-build-W-bhtml-d{envtmpdir}/doctrees。{envtmpdir}/html#我们使用Python3.7。#Tox有时会尝试根据其名称自动检测testenv，#但`docs`没有提供任何有用的线索，因此我们必须对其进行明确说明。basepython=python3.7现在，无论何时运行Tox，它都会为您的Python代码生成很好的文档。Python中的文档很棒。作为Python开发人员，我们可以使用的工具链很棒。我们可以从文档字符串开始，添加.rst文件，然后添加Sphinx和Tox来为用户美化结果。
