专栏首页Opensource翻译专栏如何使用Sphinx记录Python代码【Programming(Python)】

如何使用Sphinx记录Python代码【Programming(Python)】

文档是开发过程的最佳组成部分。 Sphinx与Tox一起,使得它易于编写,易于欣赏。

图片来源:Yuko Honda on Flickr. CC BY-SA 2.0

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为用户美化结果。

对于好的文档,您欣赏什么? 你还有其他喜欢的策略吗? 请在评论中分享它们!

原文链接:https://opensource.com/article/19/11/document-python-sphinx

原文作者: Moshe Zadka (Community Moderator)

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 约束编程示例【Programming】

    通过示例应用程序了解约束编程,该示例应用程序可以转换字符的大小写和ASCII代码。

    Potato
  • 如何使用Flask编写Python Web API【Programming(Python)】

    在此快速教程中,使用Flask(增长最快的Python框架之一)从服务器获取数据。

    Potato
  • 如何使用Protobuf进行数据交换【Programming(Go)】

    在用不同语言编写的应用程序之间以及在不同平台上运行的应用程序之间交换数据时,Protobuf 编码提高了效率。

    Potato
  • Percona Server 5.7 并行doublewrite 特性

    在这篇文章中,我们将由里及外讨论Percona Server 5.7的并行doublewrite。

    wubx
  • VBA小技巧04:使用VBA获取能够打开指定文件的EXE程序

    这是一个很有趣的技巧!可以通过你给定的文件名来获取计算机中可以打开该文件的EXE程序,即可执行程序。有时候,我们可能真的需要找到可以打开指定文件名的EXE程序,...

    fanjy
  • restful api设计最佳实践

    考虑api的安全性,建议使用https访问。 证书可使用let’s encrypt的免费证书。

    ianzhi
  • [PHP] PHP5中的写时复制change on write

    但是当新的变量值变更时 , 值从新赋予新的值时 , 就会减掉刚才的引用计数,并且从新创建内存空间.

    陶士涵
  • 解决java compiler level does not match the version of the installed java project facet

    java compiler level does not match the version of the installed java project fa...

    wust小吴
  • Excel应用实践20:使用Excel中的数据自动填写Word表格

    我想将这些数据逐行自动输入到Word文档的表格中并分别自动保存,Word文档表格如下图2所示,文档名为“datafromexcel.docx”。

    fanjy
  • Sketch67来了!可嵌入字体,性能大幅提升,你更新了吗?

    静电说:sketch现在更新的速度就像之前的Firefox浏览器一样迅速,经过几年的发展,现在几乎一个月就一个大版本,非常给力。而目前sketch67版本还算是...

    用户5009027

扫码关注云+社区

领取腾讯云代金券