如何使用Sphinx记录Python代码【Programming（Python）】

Potato

修改于 2019-12-02 11:21:12

1.2K0

修改于 2019-12-02 11:21:12

文章被收录于专栏：Opensource翻译专栏

文档是开发过程的最佳组成部分。 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代码生成漂亮的文档。