sphinx python_如何使用Sphinx记录Python代码
sphinx python
Python代码可以在其源代码中包含文档。 这样做的默认方式取决于docstrings ，它以三引号格式定义。 尽管文档的价值是有据可查的，但似乎似乎太普遍了，以至于没有足够的文档代码。 让我们来看一个关于强大文档功能的场景。
在进行了太多的白板技术采访，要求您实施斐波那契数列之后，您已经受够了。 您回家并用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模式是使用通常在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文档非常出色
docstrings ，添加 .rst文件，然后添加Sphinx和Tox为用户美化结果。您对好的文档有何评价？ 您还有其他喜欢的战术吗？ 在评论中分享他们！
翻译自: https://opensource.com/article/19/11/document-python-sphinx
sphinx python