目录

• 内联文档
  • 模块

内联文档

在本节中，您将

• 将一些代码放到模块中。
• 提供内联文档（“docstring”）。

模块

作为一个具体的例子，假设我们有一个简单的函数，它对 斯涅尔定律 进行编码。也许这个函数目前存在于 Jupyter 笔记本或电子邮件附件中的 .py 文件中。我们希望将其放到更持久、可维护、可重用和/或可共享的形式中。

以下是代码

# contents of refraction.py

import numpy as np


def snell(theta_inc: float, n1: float, n2: float) -> float:
    """
    Compute the refraction angle using Snell's Law.

    See https://en.wikipedia.org/wiki/Snell%27s_law

    Parameters
    ----------
    theta_inc : float
        Incident angle in radians.
    n1, n2 : float
        The refractive index of medium of origin and destination medium.

    Returns
    -------
    theta : float
        refraction angle

    Examples
    --------
    A ray enters an air--water boundary at pi/4 radians (45 degrees).
    Compute exit angle.

    >>> snell(np.pi/4, 1.00, 1.33)
    0.5605584137424605
    """
    return np.arcsin(n1 / n2 * np.sin(theta_inc))

请注意，此示例包含内联文档 - “docstring”。这对合作者非常有用，而最常见的合作者是未来的你！它还包括类型提示；这告诉程序员、类型检查器或 IDE 函数的输入和输出预期类型。

此外，通过遵循 numpydoc 标准，我们以后将能够自动生成外观美观的 HTML 文档。显著特征

• 在顶部，有一句话简要概述了函数的目的。它必须是一行。

• （可选）有一段详细说明该摘要。

• 有一个列出输入参数的部分，结构为

  parameter_name : parameter_type
      optional description
  

  注意 : 前面的空格。这是标准的一部分。

• 为了简洁起见，可以将类似的参数合并成一个条目，就像我们在 n1, n2 中所做的那样。

• 有一个部分描述函数返回的内容。

• （可选）有一个包含一个或多个示例的部分。

我们将在编写 文档 的部分中重新讨论文档字符串。