怎么样通过Python包生成专业的API文档

文档是很重要的

当我们使用一个新的库(或者第一百万次重复使用我们最喜欢的库)时，我们都喜欢好的和全面的文档，不是吗？

想象一下，如果他们把 Scikit-learn 或 TensorFlow 网站上的所有文档都拿走，你会有什么感觉。你会觉得很无力，不是吗？

文档是重要的。高质量的文档(特别是对于开放源码项目)证明,

• 关心这个项目
• 关心最终用户或客户(您的代码被读取的次数比编写的次数多得多)
• 具有高效的思维倾向，这样开发人员可以更有效地利用代码库进行调试和参考，或者用户可以轻松地生成错误/问题(什么是高效的数据科学)
• 一种将技术项目合理化的倾向，即不要把自己的爱好项目留在 Jupyter 笔记本的级别上，而是让它可以重复使用，并且适合更大的用户群(这样你就可以把自己与其他数据科学家区分开来)

这里有一篇文章，里面有一些很好的例子..。

但是，编写文档常常感觉像是一件苦差事。这是每个开发人员在从事大规模项目时所经历的认知负荷之上的额外负担。

如果我们有一个工具，可以生成看起来专业的文档，也就是说，可以直接从我们编写的原始 Python 函数推送到文档服务器或网站供公众使用，那会怎么样？

在本文中，我们介绍了这样一个漂亮的小工具，并给出了一些基本的例子。

‘ pdoc3’ー一个直观但强大的编写 Python 文档的工具

我们都编写了大量的 Python 函数，并为我们的数据科学项目和开放源码包创建了大量的 Python 类，不是吗？事实上，即使是对于因果分析和爱好项目，我们也应该在我们的代码库中建立这种面向对象程序设计风格的习惯。

如果能够直接从这些函数和类定义生成好看的 API 文档，而不需要编写一行额外的 HTML/CSS 代码，那将是非常简洁的。

安装和基本使用

只需要点击安装软件包,

pip install pdoc3

注意: 有一个较旧的包叫做 pdoc。您也可以将其用于文档构建，它是这个项目的一个分支。但这里我们使用的是更新的框架。

从一个简单的 add 函数开始，假设它包含在本地工作区中一个名为 math-func.py 的文件中。

def addition(num1, num2=0):
    """
    Adds two numbers

Args:

num1: The first number

num2: The second number, default 0

Returns:

The result of the addition process
“””

return (num1+num2)

因此，实际的代码只是一个返回语句，但 docstring 是长的。

这就是关键，文档字符串。

Docstring 是 pdoc 工作方式的核心。从他们的网站上看，它是“控制台应用文档可以用来渲染项目文档为静态 HTML 文件。它还包括一个实时重载的 web 服务器来预览更改。”

所以，上面的流程改变为,

那么，如何生成 web 预览呢? 只需要一个 CLI 命令。

Pdoc — http localhost: 8080 math-func.py

它在本地主机8080端口启动一个活动的 web 服务器，当你在浏览器中打开该页面时,

Starting pdoc server on localhost:8080
pdoc server ready at http://localhost:8080

你的浏览器会显示如下页面。首先，您将看到带有两个链接的页面，当您单击 math-func 链接时，您将看到 API。

很酷，不是吗? 但是它看起来很简单。让我们看看我们是否可以在它上面加上一些花里胡哨的东西。

标记——美化和实用的关键

我非常喜欢使用 markdown 格式来编写文档。您是否经常在 Github Readme 文档中使用它？关于 pdoc 的好处是它允许在 docstring 中无缝集成 markdown 文本。

假设我们将第二个函数 mult 添加到 math-func.py 模,

def mult(num1, num2=1):
    """
    Multiplies two numbers

Args:

`num1`: The first number

`num2`: The second number, default `1`

Returns:

The result of the **multiplication** process
“””

return (num1*num2)

注意文档字符串的一些细微的变化，如用标记符号‘ …’和用粗体表示的 * * * * * 。

现在，如果你只是保存这个文件，网页会自动重新载入你的修改。

请注意 num1和 num2参数是如何作为内联代码块呈现的，以及 API 文档中的乘法一词是如何以粗体显示的。这就是减价的魔力，就在你的文档里。

你甚至可以在你的文档字符串中显示一个代码块，其中有三个回标。生成的 API (用于我们的下一个除法函数) ,

我们要做的就是把这个放到文档里,

"""...Handles exception by a check,

“`python
if num2 != 0:
return (num1/num2)
else:
raise ValueError(‘The second argument cannot be zero’)
“`

“””

请注意，在三重回标之后使用了标识符 python，以便在 API 文档中以一种格式良好的方式呈现代码块。

乳胶数学

您可以在文档字符串中拥有基本的 LaTeX 数学表达式，并在 API doc 上漂亮地渲染它们。例如，我们使用下面的 docstring 编写 Pythagorian 距离计算函数,

def pythagorus(num1, num2=0):    """
    ### Description:

Calculates the root-sum-of-square of two numbers

### Args:

`num1`: The first number

`num2`: The second number, default `0`

### Returns:

The result of the **pythagorus** formula

$dist = \\sqrt { a^2+b^2 }$
“””

我们需要做以下两件事,

• 使用 $$… $包装 LaTeX 表达式
• 使用两个反斜杠字符表示 LaTeX 表达式内部的常用反斜杠。这是为了处理反斜杠作为 Python 文档字符串中的转义字符的通常角色。

结果就是,

建立功能索引

还要注意我们在页面左侧构建的函数的索引。这就像一个目录，当你点击这些链接到相应的函数时，你可以在文档的任何地方传输你的信息。这是一个模块一个模块构建的。这里我们的主要模块当然是 math-func.py 文件。

正如您可能已经注意到的，索引是按字母顺序排序的(按函数名称排序)。尽管在我们的源代码中，divide 函数的添加比 mult 函数晚，但是它的索引位于第二位。

其他选项和实用程序

我们在前一节中介绍了基本用法和选项。在这里，我们想展示一些更多的全局选项和实用程序，它们可以用于更多的控制和可用性。

输出选项

你可以生成,

• HTML pages: With pdoc — HTML < filename.py > .这将模块 HTML 文件放在。工作目录内的/html 资料夹。您可以使用一个可选的目录标志将 HTML 文件放入其中。
• 服务器: 使用 pdoc — http HOST: PORT < filename. py > 在一个网页上用用户定义的 HOST 和 PORT 显示 API 文档的实时预览。

对于类对象

您可以使用标准类对象构建文档，就像函数一样。例如，我们将整个 math-func 代码转换为一个类，并向模块中添加第二个 Dataframe 类。当我们生成文档的时候,

所有人一起

如果您将类和函数放在单个 Python 脚本(模块)中，那么它将如下所示:

程序化生成

从根本上说，pdoc3是一个 Python 包，因此您可以在 Python 代码中使用它以编程的方式生成文档。下面是一个样板代码示例,

import pdocmodules = ['a', 'b']  # Public submodules are auto-imported
context = pdoc.Context()modules = [pdoc.Module(mod, context=context)
           for mod in modules]
pdoc.link_inheritance(context)def recursive_htmls(mod):
    yield mod.name, mod.html()
    for submod in mod.submodules():
        yield from recursive_htmls(submod)for mod in modules:
    for module_name, html in recursive_htmls(mod):
        ...  # Process

注意，mod.HTML ()实质上是一个函数，在处理模块的 docstring 之后返回原始 HTML 字符串。这是使用 pdoc — html < filename.py > 命令呈现的内容。在上面的代码中，您可以直接使用代码检索它，并且无论如何都可以进一步操作它。

建立一个完整的模块

你可以使用 pdoc3一次性建立一个完整的模块。为此，您只需将必要的文件放在通常的模块/子模块层次结构中，就像标准的 Python 包一样。

例如，我们可能有这个简单的目录结构(注意 _ init _。我们将这些文件放在子目录中的 math-mod 目录中。

我们可以运行一行命令,

pdoc --http localhost:8080 -c latex_math=True math-mod

我们将得到以下结构,

摘要

构建高质量的文档可能感觉像是软件项目的编程和技术问题解决部分的额外负担。数据科学也不例外。然而，伟大的数据科学和机器学习项目和框架是真正伟大的，因为他们是多么容易被任何人使用，由于他们广泛的 API 文档。

在本文中，我们展示了如何使用一个漂亮的小 Python 包来创建漂亮的 API 文档(完整的 markdown 语法和 LaTeX 数学呈现)。

希望这能打破为您正在进行的下一个开放源码项目生成好文档的障碍。