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