如何使用 Sphinx 给 Python 代码写文档
Python 文档

> 
> 最好将文档作为开发过程的一部分。Sphinx 加上 Tox，让文档可以轻松书写，并且外观漂亮。
> 
> 
> 


![Python in a coffee cup.](/data/attachment/album/201911/29/163803d0a1ev3f40p4pk61.jpg "Python in a coffee cup.")


Python 代码可以在源码中包含文档。这种方式默认依靠 **docstring**，它以三引号格式定义。虽然文档的价值是很大的，但是没有充足的文档的代码还是很常见。让我们演练一个场景，了解出色的文档的强大功能。


经历了太多在白板技术面试上要求你实现斐波那契数列，你已经受够了。你回家用 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](https://pypi.org/) 上。`setup.py` 文件很简单：



```
import setuptools

setuptools.setup(
    name='fib',
    version='2019.1.0',
    description='Fibonacci',
    py_modules=["fib"],
)
```

但是，没有文档的代码是没有用的。因此，你可以向函数添加 docstring。我最喜欢的 docstring 样式之一是 [“Google” 样式](http://google.github.io/styleguide/pyguide.html#381-docstrings)。标记很轻量，当它放在源代码中时很好。



```
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
    """
    # ...
```

但是函数的文档只是成功的一半。普通文档对于情境化代码用法很重要。在这种情况下，情景是恼人的技术面试。


有一种添加更多文档的方式，专业 Python 人的方式通常是在 `docs/` 添加 rst 文件（ [reStructuredText](http://docutils.sourceforge.net/rst.html) 的缩写）。因此 `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](http://www.sphinx-doc.org/en/master/)，它旨在制作漂亮的 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](https://tox.readthedocs.io/en/latest/) 管理虚拟环境以确保我们顺利生成文档：



```
[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
# 我们使用 Python 3.7。
# Tox 有时会根据 testenv 的名称尝试自动检测它，
# 但是 `docs` 没有给出有用的线索，因此我们必须明确它。
basepython = python3.7
```

现在，无论何时运行 Tox，它都会为你的 Python 代码生成漂亮的文档。


### 在 Python 中写文档很好


作为 Python 开发人员，我们可以使用的工具链很棒。我们可以从 **docstring** 开始，添加 .rst 文件，然后添加 Sphinx 和 Tox 来为用户美化结果。


你对好的文档有何评价？你还有其他喜欢的方式么？请在评论中分享它们！




---


via: <https://opensource.com/article/19/11/document-python-sphinx>


作者：[Moshe Zadka](https://opensource.com/users/moshez) 选题：[lujun9972](https://github.com/lujun9972) 译者：[geekpi](https://github.com/geekpi) 校对：[wxy](https://github.com/wxy)


本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出


OK
Python code can include documentation right inside its source code. The default way of doing so relies on **docstrings**, which are defined in a triple quote format. While the value of documentation is well... documented, it seems all too common to not document code sufficiently. Let's walk through a scenario on the power of great documentation.

After one too many whiteboard tech interviews that ask you to implement the Fibonacci sequence, you have had enough. You go home and write a reusable Fibonacci calculator in Python that uses floating-point tricks to get to O(1).

The code is pretty simple:

```
# 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)
```


(That the Fibonacci sequence is a geometric sequence rounded to the nearest whole number is one of my favorite little-known math facts.)

Being a decent person, you make the code open source and put it on [PyPI](https://pypi.org/). The **setup.py** file is simple enough:

```
import setuptools
setuptools.setup(
name='fib',
version='2019.1.0',
description='Fibonacci',
py_modules=["fib"],
)
```


However, code without documentation is useless. So you add a docstring to the function. One of my favorite docstring styles is the ["Google" style](http://google.github.io/styleguide/pyguide.html#381-docstrings). It is light on markup, which is nice when it is inside the source code.

```
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
"""
# ...
```


But the function's documentation is only half the battle. Prose documentation is important for contextualizing code usage. In this case, the context is annoying tech interviews.

There is an option to add more documentation, and the Pythonic pattern is to use an **rst** file (short for [reStructuredText](http://docutils.sourceforge.net/rst.html)) commonly added under a **docs/** directory. So the **docs/index.rst** file ends up looking like this:

```
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:
```


And we're done, right? We have the text in a file. Someone should look at it.

## Making Python documentation beautiful

To make your documentation look beautiful, you can take advantage of [Sphinx](http://www.sphinx-doc.org/en/master/), which is designed to make pretty Python documents. In particular, these three Sphinx extensions are helpful:

**sphinx.ext.autodoc**: Grabs documentation from inside modules**sphinx.ext.napoleon**: Supports Google-style docstrings**sphinx.ext.viewcode**: Packages the ReStructured Text sources with the generated docs

In order to tell Sphinx what and how to generate, we configure a helper file at **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"
```


This file allows us to release our code with all the metadata we want and note our extensions (the comments above explain how). Finally, to document exactly how we want the documentation generated, use [Tox](https://tox.readthedocs.io/en/latest/) to manage the virtual environment to make sure we generate the documentation smoothly:

```
[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
```


Now, whenever you run Tox, it will generate beautiful documentation for your Python code.

## Documentation in Python is excellent


As a Python developer, the toolchain available to us is fantastic. We can start with **docstrings**, add **.rst** files, then add Sphinx and Tox to beautify the results for users.

What do you appreciate about good documentation? Do you have other favorite tactics? Share them in the comments!

## Comments are closed.