如何记录Python代码？使用文档

如果你刚刚开始使用Python, 并且想了解更多信息, 请参加srcmini的Intermediate Python课程。

使用Sphinx的Python的Pandas库文档

记录项目的相关性

无论你使用哪种编程语言, 文档都是你从事的任何项目的重要组成部分。如果项目的应用程序由各种API组成并且正在运行, 并且被许多用户使用却没有文档, 则该项目将被视为不完整。再想一想, 你自己是一名开发人员, 如果你想复制一个项目或使用一个没有文档的项目的某些方面, 会感觉如何？我相信你将很难将其与体系结构集成。

更好的文档记录将使你的项目更加成功, 因为你知道与世界共享该项目或软件时, 你希望整个世界都能使用它, 尤其是当它是开源项目时, 目标将会更多。你还希望社区为你的项目做出贡献并使其更好。

Python编程语言的著名作者引述说, “代码”的阅读比编写的频率更高。此引号应突出说明文档对他人实施的代码或项目的重要性。

想象自己是XYZ公司的一名雇员, 你正在服务通知期, 而你的经理希望你将该项目转移给你的同事。你可以给他一个KT(知识转移), 但是如果你的同事未能成功执行项目中的其中一个代码怎么办？关于代码为何不起作用的原因可能有多种, 也许你的代码运行的二进制文件与当前操作系统的二进制文件不匹配。

文档到底是什么？

文档附带有几个组件。它必须围绕这些组件进行良好的结构设计, 并遵守这些组件, 才能被视为适当的文档。

从抽象的角度来看, 这些组件是：

• 确保你的项目的代码库已正确注释。
• 它遵循Python的PEP-8编码标准。
• 有关该项目的构建方式的具体教程, 尤其是在为学习目的而开发的开源项目时。
• 如果项目还包括任何硬件, 则如何安装必要软件包, 用于构建软件的模块以及技术规格表的指南。例如, 如何安装anaconda, TensorFlow, Keras等。
• 在每个时间步上对项目进度进行的多次讨论可能导致软件的成功实施。
• 提供在开发阶段使用的技术堆栈的技术描述的参考资料。
• 项目或软件解决方案的体系结构设计。

这些要点只是结构合理, 外观完美的文档中可能存在的部分内容。保持所有这些组件的区别很重要, 这也将使将来维护文档更加容易。

包含我们讨论的大多数组件的综合文档示例将类似于如下所示：

Django的文档

很多人经常在注释和记录之间感到困惑, 并认为它们相似。注释用于向用户, 维护者甚至你自己描述代码, 以供将来参考。注释仅在代码级别起作用, 并且可以归类为文档的子集。注释有助于引导读者：

• 了解你的代码,
• 使它不言自明, 并且
• 了解其目的和设计。

请记住, 由于Python遵循PEP-8编码标准, 因此即使注释也必须遵守这些标准, 这一点很重要。 Python的官方文档指出, 要使较长的文本块具有较少的结构限制(文档字符串或注释), 因此行长应限制为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)

要更深入地了解注释及其注意事项, 请查看此有用的帖子。

现在, 让我们学习文档字符串如何帮助你记录项目代码库。

用于记录Python代码的文档字符串

Python Docstring是文档字符串, 它是字符串文字, 它出现在类, 模块, 函数或方法定义中, 并作为第一条语句编写。可以从任何Python对象的doc属性(__doc__)访问文档字符串, 并且还可以使用内置的help()函数派上用场。

同样, 文档字符串对于理解代码大部分的功能(即任何类, 模块或函数的通用目的)非常有用。相反, 注释用于代码, 语句和表达式, 它们往往很小。它们是由程序员编写的描述性文本, 主要用于自己了解代码行或表达式的功能以及希望为该项目做出贡献的开发人员。这是必不可少的部分, 文档代码将足以编写干净的代码和编写良好的程序。尽管已经提到, 但没有标准和规则。

编写文档字符串有两种形式：单行文档字符串和多行文档字符串。这些是数据科学家/程序员在其项目中使用的文档。

• 单行文档字符串是文档字符串, 它适合所有一行。你可以使用其中一种引号, 即三重单引号或三重双引号, 开始引号和结束引号必须相同。在单行文档字符串中, 右引号与右引号位于同一行。同样, 标准约定是使用三重双引号。

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.

• 多行文档字符串还包含与单行文档字符串中相同的字符串文字行, 但是其后是单个空格以及描述性文本。

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作为文档字符串格式之一, 并进行一些探索。

如你所知, 可以通过内置的Python __doc__属性和help()函数访问文档字符串。你还可以使用称为Pydoc的内置模块, 与doc属性和帮助功能相比, 该模块在功能和功能上有很大的不同。

Pydoc是一种工具, 当你想与同事共享代码或将其开源时, 它将非常方便, 在这种情况下, 你将面向更广泛的受众。它可以根据你的Python文档生成网页, 也可以启动网络服务器。

让我们看看它是如何工作的。

运行Pydoc模块的最简单便捷的方法是将其作为脚本运行。要在jupyter实验室单元中运行它, 你将使用感叹号(！)字符。

!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的第一个用途是在功能, 模块, 类等上显示文本文档。因此, 让我们看一下如何比帮助功能更好地利用它。

!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

现在, 让我们使用帮助功能提取glob文档。

help(glob)

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

NameError                                 Traceback (most recent call last)

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


NameError: name 'glob' is not defined

好了, 如你所见, 由于未定义glob, 它会引发名称错误。因此, 要使用帮助功能提取文档, 首先需要导入该模块, 而在Pydoc中则不是这种情况。

让我们探索Pydoc模块最有趣的功能, 即将Pydoc作为Web服务运行。

为此, 你只需将Pydoc作为脚本运行, 但是带有-b参数, 它将在任意未使用的端口上启动HTTP服务器, 并打开Web浏览器以交互方式浏览文档。这很有用, 尤其是当你在系统上运行各种其他服务, 并且你不记得哪个端口处于空闲状态时。

!python -m pydoc -b

^C

运行上面的单元格后, 将在任意端口号上打开一个新窗口, 并且Web浏览器的外观类似于以下所示。

让我们看一下h5py模块的文档, 它是一种用于存储神经网络体系结构权重的文件格式。

记录Python项目时的基本知识

无论目标, 远景和项目目的如何, 每个项目的文档或多或少都相同。该项目可能属于以下类别：

• 私人(个人)项目：可以用于构建项目组合或作为自由职业者来维护GitHub存储库。
• 协作(团队)项目：可以是在你的组织中运行的项目, 也可以是Kaggle竞赛中的项目。
• 开源项目：开源项目主要集中于与广泛的受众共享。它期望代码库和文档的长期协作, 贡献和可维护性。

即使以上三类项目具有不同的愿景, 文档模板也可以在所有类型的项目中共享。

假设你正在开发一个开源项目, 并且需要为其创建GitHub存储库, 该存储库应定期定期更新详细文档, 以下是你需要牢记的要点：

• 需求文件：很多时间, 作者往往会忘记这一点, 但是需求文件非常重要。它可以帮助用户快速重现你的代码。它通常是一个文本文件, 其中包含项目中使用的所有软件包, 模块以及它们各自的版本。甚至可以在自述文件中提到需求, 但是单独拥有它总是更好的, 因为用户可以使用pip命令运行该文件, 然后将所有依赖项安装在各自的系统上。
• 自述文件：自述文件通常是markdown文件格式, 它也是许多项目的基础。带有漂亮徽标的项目摘要, 功能和用途摘要。它应包括有关安装或操作项目的说明。此外, 添加自先前版本以来的所有重大更改。测试脚本或像在自述文件中成功运行其代码的快速导览一样, 将使用户更有信心进行你的项目。它还可以突出显示用户可能面临的潜在问题。
• 如何协作：这很重要, 尤其是在处理开源项目时。这应该包括新的合作者如何为该项目做出贡献。这包括开发新功能, 修复已知错误, 添加文档, 添加新测试或报告问题。协作者甚至可以发布同一项目的v2.0, 并将该项目推向更高的高度。
• 许可证：描述你的项目正在使用的许可证的纯文本文件。对于开源项目, 如Boost, Apache, MIT等许可证, 这尤其重要。这将通知用户该项目是免费的还是可以在商业上使用的程度。
• 任务分配：如果你正在处理像Kaggle这样的共享项目, 则可以定义分配给每个成员的任务以及任务的进度级别。这有助于跟踪项目中的总体进度。
• 框架可重用性：这在像Kaggle这样的共享项目中起着至关重要的作用, 在该项目中, 你的队友可以重用你可能已经构建的内容, 从而节省大量时间。例如, 数据预处理管道, 数据交叉验证脚本等。

强烈推荐的文档, 该文档的结构非常好, 并且可能是一个开源项目外观的完美示例, 然后查看GitHub存储库。

恭喜你完成了本教程。

对大家来说, 一个不错的练习是更多地探索Pydoc模块以及其他Python文档字符串格式, 例如Epydoc和Google文档字符串, 并找出它们之间的区别。

请随时在下面的评论部分中提出与本教程相关的任何问题。

参考文献：

• Python中的文档字符串

如果你刚刚开始使用Python, 并且想了解更多信息, 请参加srcmini的Intermediate Python课程。