开发文档#

提供有指导性的文档是 sktime 使命的关键部分。为了实现这一点，开发者应遵循 sktime 的文档标准。

这些包括：

  • 使用 NumPy 文档字符串和 sktime 约定记录代码

  • 遵循 sktime 的公共代码工件和模块的文档字符串约定

  • 向 API 参考 和 notebook examples 添加新的公共功能

关于 sktime 文档格式的更多详细信息如下所示。

文档字符串约定#

sktime 使用 numpydoc Sphinx 扩展，并遵循 NumPy 文档字符串格式。

为了确保文档字符串符合预期，sktime 使用了 numpydoc 内置的验证、pydocstyle 预提交检查（设置为 NumPy 约定）以及自动测试文档字符串示例以确保代码无误的组合。然而，pydocstyle 中的自动文档字符串验证仅涵盖基本格式。通过这些测试是符合 sktime 文档字符串约定的必要条件，但不足以完全满足这些约定。

为了确保文档字符串符合 sktime 的约定，开发者应根据 numpydoc 和 sktime 的约定检查其文档字符串，并且 评审者 也应将反馈重点放在文档字符串的质量上。

sktime 特定约定#

除了基本的 NumPy 文档字符串格式约定外，开发者还应关注：

  • 确保所有参数（类、函数、方法）和属性（类）都得到完整且一致的文档记录

  • 在扩展摘要中包含相关主题的链接，如 术语表 或 示例。

  • 包含一个 示例 部分，该部分展示了所有公共代码工件中的至少基本功能

  • 添加一个 参见 部分，引用相关的 sktime 代码工件（如适用）

  • 在 References 部分中引用相关来源

备注

在许多情况下，参数、属性返回对象或错误可能在 sktime 的多个文档字符串中被描述。为了避免混淆，开发者应确保他们的文档字符串尽可能与现有相同参数、属性、返回对象或错误的文档字符串描述相似。

因此，sktime 估计器和大多数其他公共代码制品通常应包括以下 NumPy 文档字符串约定部分：

  1. 摘要

  2. 扩展摘要

  3. 参数

  4. 属性（仅限类）

  5. 返回或生成（视情况而定）

  6. 引发（如适用）

  7. 另请参阅（如适用）

  8. 备注（如适用）

  9. 参考文献（如适用）

  10. 示例

摘要和扩展摘要#

摘要应为单行，其后跟随一个（格式正确的）扩展摘要。扩展摘要应包括对代码工件功能的用户友好解释。

对于所有实现算法的 sktime 估计器和其他代码工件（例如性能指标），扩展摘要应包括所实现算法的简短、用户友好的概述。当算法使用多个 sktime 估计器实现时，概述应首先提供估计器组件的高级摘要（例如，首先应用 transformer1，然后是分类器）。接下来应提供算法的其他用户友好细节（例如，描述转换和分类器如何工作）。

扩展摘要还应包括指向 术语表 和 笔记本示例 中相关内容的链接。

如果术语已经在术语表中存在，并且开发者希望直接链接到它，他们可以使用：

:term:`the glossary term`

在其他情况下，您可能希望使用不同的措辞但链接到现有的术语表条目，开发人员可以使用：

:term:`the link text <the glossary term>`

如果术语尚未在术语表中，开发者应将该术语添加到术语表（sktime/docs/source/glossary.rst）中，并包含对所添加术语的引用（如上所示）。

同样，开发者可以通过包含一个明确的交叉引用并遵循Sphinx中的引用步骤（参见Read the Docs发布的关于`Sphinx交叉引用 <https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_ 的有用描述）来链接到用户指南的特定区域。再次鼓励开发者将重要内容添加到用户指南中，并在其尚不存在时链接到它。

另请参阅#

本节应引用与正在通过文档字符串记录的代码工件相关的其他 sktime 代码工件。开发人员应使用判断来确定相关的代码工件。例如，基于百分比误差的性能指标可能只列出其他基于百分比误差的性能指标，而不是列出所有其他性能指标。同样，基于距离的分类器可能列出其他基于距离的分类器，但不包括其他类型的时间序列分类器。

注释#

注释部分可以包括几种信息，包括：

  • 代码对象的数学细节或其他重要实现细节（使用 ..math 或 :math:`` 功能）

  • 链接到 sktime 外部的代码工件的替代实现（例如，sktime 时间序列分类器的 Java 实现）

  • 状态改变方法 (sktime 估计器类)

参考文献#

实现具体算法的 sktime 估计器通常应包括对描述该算法的原始研究文章、教科书或其他资源的引用。其他代码工件可以根据需要包含引用（例如，sktime 的性能指标中包含相关论文的引用）。

这应该通过在文档字符串的参考部分添加参考来完成，然后在文档字符串的其他部分通常链接到这些参考。

您打算在文档字符串中链接的引用应遵循非常特定的格式，以确保它们正确呈现。请参见下面的示例。注意“..”和左括号之间的空格，右括号后的空格，以及第一行之后的所有行如何与左括号立即对齐。其他引用应以完全相同的方式添加，但括号中包含的数字应递增。

.. [1] Some research article, link or other type of citation.
   Long references wrap onto multiple lines, but you need to
   indent them so they start aligned with opening bracket on first line.

要链接到标记为“[1]”的引用，请使用“[1]_”。这仅在同一文档字符串内有效。有时如果“[1]_”链接的前后有某些字符，可能无法正确渲染。如果遇到此问题，请尝试在“[1]_”链接前后添加空格。

要在文档字符串中列出引用但不链接到其他地方，可以省略“.. [1]”指令，如下所示。

Some research article, link or other type of citation.
Long references wrap onto multiple lines. If you are
not linking the reference you can leave off the ".. [1]".

示例#

sktime 中的大多数代码工件应包含一个示例部分。至少应包括一个展示基本功能的示例。示例应使用内置的 sktime 数据集或其他简单数据（例如随机生成的数据等），这些数据应使用 sktime 依赖项（例如 NumPy、pandas 等）生成，并且尽可能仅依赖于 sktime 或其核心依赖项。示例还应设计为尽可能快速运行。对于快速运行的代码工件，可以包含额外的示例来说明不同参数设置的影响。

优秀 sktime 文档字符串的示例#

以下是一些具有良好文档的 sktime 代码工件示例。

估计器#

BOSSEnsemble

ContractableBOSS

性能指标#

MeanAbsoluteScaledError

文档构建#

我们使用 sphinx 来构建我们的文档，并使用 readthedocs 来托管它。您可以在 这里 找到我们最新的文档。

源文件可以在 docs/source/ 找到。Sphinx 的主配置文件是 conf.py，主页面是 index.rst。要添加新页面，你需要添加一个新的 .rst 文件并将其包含在 index.rst 文件中。

要在本地构建文档，您需要安装 pyproject.toml 中列出的几个额外依赖项。

  1. 要为构建文档安装额外的依赖项，请运行：

    pip install --editable .[docs]

  2. 要在本地构建网站，请导航到 docs/source 并执行：

    make html

    请注意，初始构建可能需要长达20分钟。后续针对增量变化的构建将会显著加快。

  3. 要进行干净的构建，请运行：

    make clean html

  4. 在编辑文档时，可以使用 sphinx-autobuild 进行实时重载。

    首先，通过运行以下命令安装 sphinx-autobuild：

    pip install sphinx-autobuild

    然后在 docs/source 中运行：

    make autobuild
On this page