开发文档

aeon的文档标准包括：

  • 使用numpydoc文档字符串约定记录代码

  • 向api_reference添加新的公共功能。

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

文档字符串约定

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

为了确保文档字符串符合预期，aeon 使用了内置在 numpydoc 和 pydocstyle 中的验证组合，以及 pre-commit 检查（设置为 NumPy 约定），并通过自动化测试文档字符串示例来确保代码运行无误。

除了基本的NumPy文档字符串格式化约定外，开发人员还应努力：

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

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

  • 在参考文献部分中包含相关来源的引用

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

  • 文档字符串被渲染成.rst文件，并且在编写时应考虑到这一点。例如，代码块需要两个`字符，而不是Markdown中使用的一个。

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

aeon 通常应包含 numpydoc 部分，按以下顺序适用：

  1. 摘要

  2. 扩展摘要

  3. 参数

  4. 属性（仅限类）

  5. 返回/产出（仅限函数/方法）

  6. 引发（仅限函数/方法）

  7. 另请参阅

  8. 注释

  9. 参考文献

  10. 示例

摘要和扩展摘要

摘要应为一句话，后接扩展摘要。扩展摘要应包括对代码功能的用户友好解释，即对所实现算法的简短、用户友好的概述或对估计器组件的高级总结。

参数和属性

所有参数和拟合属性（任何公共属性，即在fit中设置并以_结尾的属性）应在文档字符串中列出。每个参数和属性应包括描述、类型和默认值（如果适用）。例如：

n_jobs : int, default=1
    The number of jobs to run in parallel for both ``fit`` and ``predict``.
    ``-1`` means using all processors.

没有默认值或属性的参数不需要包含默认值：

n_cases_ : int
    Number of train instances in data passed to ``fit``.

另请参阅

本节应参考与所记录代码相关的其他aeon代码。 例如，Catch22管道分类器可以参考Catch22特征 转换和管道回归器。

ContractableBOSS
    Variant of the BOSS classifier.
WEASEL
    SFA based pipeline extending from BOSS.
SFA
    The Symbolic Fourier Approximation feature transformation used in BOSS.

注释

注释部分可以包含有用但不适合放在其他部分或扩展摘要中的信息。由开发者自行决定。一些例子包括：

  • 链接到aeon外部的代码替代实现

  • 链接到使用或从中获得灵感的代码（有时这在扩展摘要中更好）

  • 代码的怪癖或限制的解释

参考文献

aeon 实现已发布算法的估计器通常应包括对原始文章的引用（包括arxiv等）。与代码相关的其他论文，如评估或扩展，也可以包括在内。

参考文献必须按照以下格式包含：

.. [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]_, [2]_。这仅在同一个文档字符串内有效。在引用标签和文档字符串中的其他文本之间包含空格。

示例

大多数在aeon中的公共代码应该包含一个示例部分。至少，这应该包括一个展示基本功能的示例。示例应尽可能使用内置的aeon数据集或其他简单数据（例如随机生成的数据）。示例还应尽可能设计为快速运行。

>>> import numpy as np
>>> from aeon.distances import dtw_distance
>>> x = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
>>> y = np.array([11, 12, 13, 14, 15, 16, 17, 18, 19, 20])
>>> dtw_distance(x, y) # 1D series
768.0

>>> x = np.array([[1, 2, 3, 4, 5], [6, 7, 8, 9, 10], [0, 1, 0, 2, 0]])
>>> y = np.array([[11, 12, 13, 14],[7, 8, 9, 20],[1, 3, 4, 5]] )
>>> dtw_distance(x, y) # 2D series with 3 channels, unequal length
564.0

>>> 用于表示一行代码。可以使用 ... 来继续一行，例如，如果你有一个很长的导入语句，你可能想要这样做：

>>> from aeon.classification.dictionary_based import (
...     BOSSEnsemble
... )

良好的aeon文档字符串示例

这里有一些带有良好文档的aeon代码示例。

估计器

BOSSEnsemble

函数

dtw_distance

文档构建

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

源文件可以在docs/中找到。 Sphinx的主要配置文件是conf.py， 主页是index.md。 要添加新页面，您需要添加一个新的.md（或.rst，但最好是Markdown） 文件，并将其包含在toctree中以将其包含在侧边栏中。

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

  1. 要从根目录安装文档依赖项，请运行：

pip install --editable .[docs]

  1. 切换到文档目录：

cd docs

注意： 如果您使用的是Linux或MacOS，您需要安装Pandoc作为依赖项。使用以下命令进行安装：

如果您使用的是任何基于Debian的系统，您可以使用以下命令来安装Pandoc：

sudo apt install pandoc

如果您使用的是MacOS，您可以使用以下命令来安装Pandoc：

brew install pandoc

对于所有其他操作系统，请查看Pandoc安装指南。

  1. 要在本地构建网站，请运行：

make html

对于Windows，请改用：

make.bat html

这将在docs/_build/html中生成HTML文档。如果您进行了任何更改，请重复步骤3以重新生成文件。