良许Linux教程网 干货合集 使用Sphinx创建Python代码写文档

使用Sphinx创建Python代码写文档

Sphinx 是由 Georg Brandl 编写的工具,可轻松为 Python 项目(或由多个 reStructuredText 源组成的其他文档)创建智能且美观的文档。它最初是为新的 Python 文档创建的,具有用于Python项目文档的出色功能,但同时也支持C / C ++,并且计划了更多的语言。

image-20220129184417900

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 上。setup.py 文件很简单:

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

但是,没有文档的代码是没有用的。因此,你可以向函数添加 docstring。我最喜欢的 docstring 样式之一是 “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
   """
   # ...

但是函数的文档只是成功的一半。普通文档对于情境化代码用法很重要。在这种情况下,情景是恼人的技术面试。 有一种添加更多文档的方式,专业 Python 人的方式通常是在 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 样式的 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 管理虚拟环境以确保我们顺利生成文档:

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

以上就是良许教程网为各位朋友分享的Linu系统相关内容。想要了解更多Linux相关知识记得关注公众号“良许Linux”,或扫描下方二维码进行关注,更多干货等着你 !

img
本文由 良许Linux教程网 发布,可自由转载、引用,但需署名作者且注明文章出处。如转载至微信公众号,请在文末添加作者公众号二维码。
良许

作者: 良许

良许,世界500强企业Linux开发工程师,公众号【良许Linux】的作者,全网拥有超30W粉丝。个人标签:创业者,CSDN学院讲师,副业达人,流量玩家,摄影爱好者。
上一篇
下一篇

发表评论

邮箱地址不会被公开。 必填项已用*标注

联系我们

联系我们

公众号:良许Linux

在线咨询: QQ交谈

邮箱: yychuyu@163.com

关注微信
微信扫一扫关注我们

微信扫一扫关注我们

关注微博
返回顶部