编写 Python 文档：操作指南

如果您刚开始学习 Python 并希望进一步提升，欢迎参加 DataCamp 的Intermediate Python课程。

pandas — Python 的 Pandas 库文档（使用 Sphinx）</a

为项目编写文档的重要性

无论您使用哪种编程语言，文档都是任何项目不可或缺的一部分。一个项目即使拥有完整可用、被众多用户调用的各种 API，如果没有文档，也会被视为不完整。想象一下，作为一名开发者，当您想要复现某个项目或使用其中某个部分，而它却没有任何文档时，您会作何感想？要把它集成到您的架构中，恐怕会相当艰难。

更完善的文档会让您的项目更成功。因为当您将项目或软件分享给世界时，您当然希望更多人来使用它；尤其是开源项目，这一目标更为明显。您也会希望社区能为您的项目做出贡献，让它变得更好。

Python 语言的著名作者曾说过：代码被阅读的次数多于被编写的次数。 这句话凸显了文档对于他人实现您的代码或项目的重要性。

设想您在XYZ公司工作，正处于离职交接期，经理希望您把项目移交给同事。您也许会进行一次 KT（知识转移），但如果您的同事无法成功运行项目中的某段代码怎么办？导致代码无法运行的原因可能有很多，比如您的代码所依赖的二进制环境与当前操作系统的二进制不匹配。

什么才是“文档”？

文档由多个组成部分构成。只有围绕这些部分进行良好组织并遵循相应规范，才能称得上合格的文档。

从抽象层面看，这些组件包括：

确保项目代码库有充分的注释。
遵循 Python 的 PEP 8 编码规范。
提供关于项目如何构建的具体教程，特别是以学习为导向的开源项目。
安装指南：如何安装用于构建软件所需的包和模块；如果项目包含硬件，还应提供技术规格表。例如，如何安装 anaconda、TensorFlow、Keras 等。
在各个时间节点对项目进展进行多次讨论，记录促成软件成功实现的关键点。
参考资料：对开发阶段使用的技术栈进行技术性描述。
项目或软件解决方案的架构设计。

以上只是结构良好、看起来完备的文档可能包含的一部分组件。保持这些部分各自独立非常重要，这也有助于未来维护文档。

一个包含了我们讨论的大多数组件的全面文档示例如下所示：

许多人常常把注释与文档混淆，认为二者相同。注释用于向用户、维护者，甚至是您自己（作为将来的参考）描述代码。注释仅在代码层面起作用，可以看作是文档的子集。注释帮助读者：

理解您的代码，
让代码自我说明，
理解其目的与设计。

需要牢记的是，既然 Python 遵循 PEP 8 编码规范，那么注释也必须遵循这些规范。Python 官方文档指出，对于结构限制较少的长文本块（docstring 或注释），行长度应限制在 72 个字符。

要检查代码是否遵循 PEP 8 标准，您可以使用 Python 的 pylint 模块。该模块还可用于修改注释及其他代码行的字符限制。

下面来看几个例子。

导入模块的说明

import tensorflow as tf
#imports tensorflow as tf. Tensorflow is an n-dimensional matrix.
#just like a 1-D vector, 2-D array, 3-D array etc.
技术支持

变量定义说明

n_classes = 10 # MNIST total classes (0-9 digits)
技术支持

若想更深入了解注释及其注意事项，请查看这篇文章。

接下来一起学习 docstring 如何帮助为您的项目代码库编写文档。

使用 Docstring 为 Python 代码编写文档

Python Docstring（文档字符串）是出现在类、模块、函数或方法定义中的字符串字面量，作为其首个语句出现。任意 Python 对象的 doc 属性(__doc__)都可以访问到 docstring，同时内置的 help() 函数也非常实用。

Docstring 很适合理解较大代码单元的功能，即某个类、模块或函数的一般用途。相较之下，注释用于代码、语句与表达式层面，往往更细小。它们是程序员为自己（以及有意为该项目做出贡献的开发者）编写的描述性文字，用来说明某行代码或表达式的作用。为代码编写文档是撰写整洁代码与优质程序的重要一环。虽然前面已提到，但对撰写方式并没有严格的统一标准与规则。

Docstring 有两种形式：单行 Docstring 与多行 Docstring。数据科学家/程序员在项目中通常会使用这两类文档。

单行 Docstring 顾名思义，一行即可写完。可以使用三引号，单引号或双引号均可，且首尾需一致。单行 Docstring 的结束引号与起始引号位于同一行。通常的惯例是使用三重双引号。

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)


help(square)
技术支持

Returned argument a is squared.
Help on function square in module __main__:

square(a)
    Returned argument a is squared.
技术支持

多行 Docstring 与单行 Docstring 一样以字符串字面量开头，但随后会有一个空行并跟随更为详细的描述性文本。

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)
技术支持

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value
技术支持

从上表中，让我们选择 Pydoc 作为一种 docstring 格式，进一步探索一下。

如您所知，可以通过 Python 内置的 __doc__ 属性和 help() 函数访问 docstring。您还可以使用内置模块 Pydoc，与 doc 属性和 help 函数相比，它在功能与特性上有很大不同。

Pydoc 在您想与同事共享代码或将其开源时非常有用，此时您的受众会更广。它可以从 Python 文档生成网页，也能启动一个 Web 服务器。

看看它如何工作。

最简单方便的运行 Pydoc 的方式是将其作为脚本运行。在 jupyter lab 单元格中运行时，您需要使用感叹号（!）。

!python -m pydoc
技术支持

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.
技术支持

从上面的输出可以看到，Pydoc 的首要用途是展示函数、模块、类等的文本文档。接下来看看如何比 help 函数更好地利用它。

!python -m pydoc glob
技术支持

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py
技术支持

现在，使用 help 函数来提取 glob 的文档。

help(glob)
技术支持

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-13-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined
技术支持

如您所见，这里抛出了 name error，因为 glob 未定义。也就是说，若要使用 help 函数提取某模块的文档，您需要先导入该模块；而使用 Pydoc 则无此限制。

接下来探索 Pydoc 模块最有趣的功能：将 Pydoc 作为 Web 服务运行。

为此，只需仍以脚本方式运行 Pydoc，但加上 -b 参数，它会在任意空闲端口启动一个 HTTP 服务器，并打开浏览器以交互式浏览文档。这在系统中运行了多个其他服务、且不确定哪个端口空闲时尤其有用。

!python -m pydoc -b
技术支持

^C
技术支持

当您运行上述单元格时，会在某个随机端口打开一个新窗口，浏览器界面类似下图。

我们来查看一下 h5py 模块的文档。它是一种用于存储神经网络架构权重的文件格式。

为 Python 项目编写文档的要点

无论项目的目标、愿景与用途为何，文档在不同项目间大体相似。项目可能属于以下类别：

私有（个人）项目：用于打造作品集，或以自由职业者身份维护 GitHub 仓库。
协作（团队）项目：如在您的组织内部开展的项目，或参与 Kaggle 竞赛。
开源项目：主要面向更广泛的受众分享，期望协作、贡献，并在长期内保持代码库与文档的可维护性。

尽管上述三类项目愿景不同，但文档模板可在各类项目中通用。

假设您正在进行一个开源项目，需要创建一个 GitHub 仓库并定期更新详细文档，那么以下是您需要牢记的要点：

依赖清单（Requirements 文件）：作者常常会忽略这一点，但它非常重要。它帮助用户快速复现您的代码。通常是一个文本文件，包含项目中使用的所有包和模块及其版本。依赖也可以写在 Readme 中，但单独成文件更好，因为用户可以直接用 pip 命令运行该文件，在其系统上安装所有依赖。
Readme：Readme 通常为 Markdown 格式，是许多项目的“骨架”。其中应包含项目摘要、功能与目的，并配有合适的 Logo；应包含安装或运行项目的说明；此外，还可添加与上一版本相比的重要变更。在 Readme 中附上测试脚本或“快速上手”示例、有助于用户成功运行代码，会使用户更有信心继续使用您的项目。还可以提示用户可能遇到的潜在问题。
协作方式：在开源项目中尤为重要。应说明新合作者如何为项目做出贡献，包括开发新功能、修复已知 Bug、补充文档、添加新测试或提交问题等。合作者甚至可以发布 v2.0 版本，将项目提升到新的高度。
许可证：一份纯文本文件，描述项目所使用的许可证。对开源项目尤其关键，例如 Boost、Apache、MIT 等。它告知用户该项目是否可用于商业用途，以及使用范围。
任务分配：如果您在进行类似 Kaggle 的共享项目，可以定义每位成员被分配的任务及其进度，以便跟踪项目整体进展。
框架复用性：在类似 Kaggle 的共享项目中，这一点至关重要。队友可以复用您已经构建的内容，从而大幅节省时间。例如，数据预处理流水线、数据交叉验证脚本等。

强烈推荐查看结构非常完善、可作为开源项目范例的 huggingface transformers GitHub 仓库。

结语

恭喜您完成本教程。

一个不错的练习是进一步探索 Pydoc 模块，以及 Epydoc、Google 风格 docstring 等其他 Python 文档字符串格式，并比较它们之间的差异。

如对本教程有任何疑问，欢迎在下方评论区留言。

参考资料：

Docstrings in Python

如果您刚开始学习 Python 并希望进一步提升，欢迎参加 DataCamp 的Intermediate Python课程。

主题

Python 数据科学

主题

技术

如何为 Python 代码编写文档

使用 AI 探索

为项目编写文档的重要性

什么才是“文档”？

使用 Docstring 为 Python 代码编写文档

为 Python 项目编写文档的要点

结语

主题

Python 课程

Python 入门

Python 中级

Python 数据科学入门

主题

技术

Python 课程

Python 入门

Python 中级

Python 数据科学入门