如何使用Sphinx记录Python代码【Programming（Python）】
如何使用Sphinx记录Python代码【Programming（Python）】
文档是开发过程的最佳组成部分。 Sphinx与Tox一起，使得它易于编写，易于欣赏。
Python代码可以在其源代码中包含文档。 这样做的默认方式依赖于docstrings ，它们以三引号格式定义。 虽然文档的价值是有据可查的，但似乎似乎很普遍，没有足够的文档代码。 让我们来看一个有关强大文档功能的场景。
经过太多的白板技术面试，要求你实现斐波那契序列，你已经受够了。 回到家，编写一个可重用的斐波那契计算器，它使用浮点技巧实现了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模式是使用通常在docs /目录下添加的rst文件（ reStructuredText的缩写）。 因此， 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开发人员，我们可以使用的工具链很棒。 我们可以从docstrings开始，添加.rst文件，然后添加Sphinx和Tox为用户美化结果。
对于好的文档，您欣赏什么？ 你还有其他喜欢的策略吗？ 请在评论中分享它们！
本文系外文翻译，前往查看
如有侵权，请联系 cloudcommunity@tencent.com 删除。
本文系外文翻译，前往查看
如有侵权，请联系 cloudcommunity@tencent.com 删除。