SpeechBrain 文档

请安装额外的依赖项

pip install -r docs-requirements.txt

然后运行

make html

以构建 HTML 文档。然后打开 build/html/index.html

从 docstrings 自动生成 API 文档

文档使用 sphinx.ext.napoleon 支持 Google 风格的 docstrings。Sphinx 原生支持 reStructuredText 指令。

基于 docstrings 自动生成文档不是 Sphinx 的核心功能。为此，经过大量搜索，我们使用了 better-apidoc。

教程集成

教程现在位于主 SpeechBrain 仓库中。

教程贡献者指南

docs/tutorials 目录专门包含 Jupyter Notebook 格式的教程。这些教程半自动化地集成到文档中。你应该确保遵守以下步骤，以便它们正确渲染，并保持一致的质量。

相对重要的注意事项

  • 创建你的新 notebook，最好与现有教程具有相同的结构。

  • 保持文件大小小！限制图片和音频。

    • 理想情况下，总大小应在几百 KiB 左右，除非万不得已，否则避免超过 1MiB。

    • 如果用户必须运行 notebook 才能获得一些更大的输出，那也没关系。

  • 最好使用 Jupyter Notebook 进行 notebook 的最终编辑。

    • Jupyter Notebook 的 .ipynb 输出通常比较合理。这可以避免 Git diff 过大。

  • 图片可以放在 docs/tutorials/assets 目录中， 而不是作为 base64 嵌入。然后你可以在 Markdown 中引用它们，例如 ![alt text](../assets/myimage.png)。这些在导入到 Colab 时也能正常工作。

    • 选择具有描述性的名称。

文档集成

  • 将你的 notebook 添加到相关的类别 .rst 文件中，注意保持与现有教程相同的结构和外观。

    • （如果确实必要，可以创建一个新类别，但这会使目录/侧边栏变得臃肿。）

  • Colab 头部/引用尾部是自动生成的，不应手动插入或编辑。请参阅 tools/tutorial-cell-update.py。你应该对你的 notebook 运行此脚本。

  • 将你的 notebook 添加到同一文档的隐藏 toctree 中。

  • 确保你的标题一致！

    • 请为 notebook 的标题使用单个顶级标题。

    • 该标题应与摘要中的名称匹配。

    • 对于所有其他内容，请使用二级或更深层标题（在 markdown 中使用 ##, ### 等）。Notebook 标题**会**用作文档树的一部分！

  • 确保你的教程在文档内视图中至少能正确渲染。

    • 你可以通过正常生成文档或使用 readthedocs PR 集成来检查，该集成允许你预览 PR 的文档（假设成功）。但这需要时间！贡献时最好有一个功能正常的文档环境。