开发文档#

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

这包括

  • 使用 NumPy docstring 和 sktime 约定来编写代码文档

  • 遵循 sktime 对公共代码artifact和模块的 docstring 约定

  • 将新的公共功能添加到 API 参考 和 notebook 示例 中

下面提供了关于 sktime's 文档格式的更详细信息。

Docstring 约定#

sktime 使用 numpydoc Sphinx 扩展，并遵循 NumPy docstring 格式。

为确保 docstring 符合预期，sktime 结合使用了 numpydoc 内置的验证、pydocstyle pre-commit 检查（设置为 NumPy 约定）以及 docstring 示例的自动化测试，以确保代码无误运行。然而，pydocstyle 中的自动化 docstring 验证仅涵盖基本格式。通过这些测试是满足 sktime docstring 约定的必要条件，但非充分条件。

为确保 docstring 符合 sktime 的约定，开发者应对照 numpydoc 和 sktime 约定检查其 docstring，且 审阅者 也应将重点放在 docstring 质量的反馈上。

sktime 特定约定#

除了基本的 NumPy docstring 格式约定外，开发者还应关注

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

  • 在扩展概要中包含指向 常用术语表 或 Notebook 示例 中相关主题的链接

  • 在所有公共代码artifact中包含一个 示例 部分，以演示至少基本功能

  • 酌情添加一个 另请参阅 部分，以引用相关的 sktime 代码artifact

  • 在 引用 部分中包含对相关来源的引用

注意

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

因此，sktime 估计器和大多数其他公共代码artifact通常应包含以下 NumPy docstring 约定部分

  1. 概要

  2. 扩展概要

  3. 参数

  4. 属性（仅类）

  5. 返回或 Yield（如适用）

  6. 抛出（如适用）

  7. 另请参阅（如适用）

  8. 注意（如适用）

  9. 引用（如适用）

  10. 示例

概要和扩展概要#

概要应为单行，后接（正确格式化的）扩展概要。扩展概要应包含对代码artifact功能的易于理解的解释。

对于所有实现算法（例如性能指标）的 sktime 估计器和其他代码artifact，扩展概要应包含所实现算法的简短、易于理解的摘要。当算法使用多个 sktime 估计器实现时，摘要应首先提供估计器组件的高级摘要（例如，先应用 transformer1，然后应用分类器）。随后应提供关于算法的其他易于理解的详细信息（例如，描述转换器和分类器如何工作）。

扩展概要还应包含指向 常用术语表 和 notebook 示例 中相关内容的链接。

如果词汇表中已存在某个“术语”，并且开发者想要直接链接到它，他们可以使用

:term:`the glossary term`

在其他情况下，您可能希望使用不同的措辞，但链接到现有的词汇表术语，开发者可以使用

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

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

同样，开发者可以通过包含显式交叉引用并遵循 Sphinx 中的引用步骤（参见 Read the Docs 发布的关于 Sphinx 交叉引用 的有用描述），链接到用户指南的特定区域。再次鼓励开发者将重要内容添加到用户指南中，如果尚不存在，则链接到该内容。

另请参阅#

本节应引用与 docstring 所记录的代码artifact相关的其他 sktime 代码artifact。开发者在确定相关的代码artifact时应运用判断力。例如，基于百分比误差的性能指标可能只列出其他基于百分比误差的性能指标，而不是列出所有其他性能指标。同样，基于距离的分类器可能列出其他基于距离的分类器，但不包括其他类型的时间序列分类器。

注意#

注意部分可以包含几种类型的信息，包括

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

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

  • 状态改变方法（sktime 估计器类）

引用#

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

这应该通过将引用添加到 docstring 的引用部分，然后通常在 docstring 的其他部分链接到这些引用来完成。

您打算在 docstring 中链接的引用应遵循非常特定的格式，以确保它们正确渲染。参见下面的示例。注意“..”和开方括号之间的空格，闭方括号后的空格，以及第一行之后的所有行如何与开方括号对齐。应以完全相同的方式添加其他引用，但方括号内的数字应递增。

.. [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]_”。这仅在同一 docstring 内有效。有时，如果“[1]_”链接前后紧跟某些字符，则可能无法正确渲染。如果您遇到此问题，请尝试在“[1]_”链接前后加一个空格。

要列出引用但不将其链接到 docstring 的其他地方，您可以省略“.. [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 中的大多数代码artifact都应包含一个示例部分。至少应包含一个示例，说明基本功能。示例应使用内置的 sktime 数据集或其他使用 sktime 依赖项（例如 NumPy、pandas 等）生成的简单数据（例如随机生成的数据等），并尽可能只依赖于 sktime 或其核心依赖项。示例设计上也应尽可能快速运行。对于快速运行的代码artifact，可以包含其他示例来展示不同参数设置的影响。

良好的 sktime Docstring 示例#

以下是几个具有良好文档的 sktime 代码artifact示例。

估计器#

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