前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >如何使用Sphinx记录Python代码【Programming(Python)】

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

作者头像
Potato
修改2019-12-02 11:21:12
1.2K0
修改2019-12-02 11:21:12
举报
文章被收录于专栏:Opensource翻译专栏

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

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

Python代码可以在其源代码中包含文档。 这样做的默认方式依赖于docstrings ,它们以三引号格式定义。 虽然文档的价值是有据可查的,但似乎似乎很普遍,没有足够的文档代码。 让我们来看一个有关强大文档功能的场景。

经过太多的白板技术面试,要求你实现斐波那契序列,你已经受够了。 回到家,编写一个可重用的斐波那契计算器,它使用浮点技巧实现了O(1)。

代码很简单:

代码语言:javascript
复制
# 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文件非常简单:

代码语言:javascript
复制
import setuptools
 
 setuptools.setup(
     name='fib',
     version='2019.1.0',
     description='Fibonacci',
     py_modules=["fib"],
 )

但是,没有文档的代码是没有用的。 因此,您可以向函数添加文档字符串。 我最喜欢的文档字符串样式之一是“ Google”样式 。 标记很轻巧,当它位于源代码中时很好。

代码语言:javascript
复制
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文件最终看起来像这样:

代码语言:javascript
复制
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中配置一个辅助文件:

代码语言:javascript
复制
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 来管理虚拟环境,以确保我们顺利地生成文档:

代码语言:javascript
复制
[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为用户美化结果。

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

本文系外文翻译,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文系外文翻译前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 使Python文档更漂亮
  • Python文档非常出色
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档