文档

TVM 文档大致遵循 Divio 描述的正式文档风格。选择此系统是因为它是一个“简单、全面且几乎普遍适用的方案。它已在各种领域和应用中得到实践证明。”

本文档描述了 TVM 文档的组织结构，以及如何编写新文档。有关构建文档的说明，请参阅 docs/README.md。

这些是指导新用户入门项目的逐步指南。入门教程旨在让用户参与到软件中，而不必解释软件的工作原理。这些解释可以留给其他文档类型。入门教程侧重于成功的首次体验。这些是将新手转变为新用户和开发人员的最重要的文档。一个完整的端到端教程 — 从安装 TVM 和支持 ML 软件，到创建和训练模型，再到编译到不同的架构 — 将为新用户提供以最有效方式使用 TVM 的机会。教程教给初学者他们需要知道的东西。这与操作指南形成对比，操作指南旨在回答有一定经验的用户会提出的问题。

教程需要是可重复且可靠的，因为缺乏成功意味着用户会寻找其他解决方案。

操作指南 

这些是关于如何解决特定问题的逐步指南。用户可以提出有意义的问题，文档提供答案。此类文档的示例可能是“如何为 ARM 架构编译优化模型？”或“如何编译和优化 TensorFlow 模型？”这些文档应该足够开放，以便用户可以看到如何将其应用于新的用例。实用性比完整性更重要。标题应该告诉用户操作指南正在解决什么问题。

教程与操作指南有何不同？教程面向新的开发人员，侧重于成功地将他们介绍给软件和社区。相比之下，操作指南侧重于在基本理解的背景下完成特定任务。教程有助于入门，并且不假设任何先前的知识。操作指南假设最少的知识，旨在指导某人完成特定任务。

参考 

参考文档描述了软件的配置和操作方式。API、关键函数、命令和接口都是参考文档的候选对象。这些是技术手册，让用户可以构建自己的接口和程序。它们以信息为导向，侧重于列表和描述。您可以假设受众掌握了软件的工作原理，并且正在寻找针对特定问题的具体答案。理想情况下，参考文档应具有与代码库相同的结构，并尽可能自动生成。

架构指南 

架构指南是对某个主题的解释和背景资料。这些文档有助于阐明和理解应用环境。事情为什么是这样的？设计决策是什么，考虑了哪些替代方案，描述现有系统的 RFC 是什么？这包括学术论文和与软件相关的出版物的链接。在这些文档中，您可以探讨矛盾和冲突的立场，并帮助读者理解软件是如何以及为什么以现在的方式构建的。这里不是介绍操作指南和如何完成任务的地方。相反，它们侧重于更高层次的概念，这些概念有助于理解项目。通常，这些文档由项目的架构师和开发人员编写，但可以帮助用户和开发人员更深入地了解软件的工作原理，以及如何以符合底层设计原则的方式为其做出贡献。

TVM 的特殊考虑 

TVM 社区有一些特殊的考虑因素，需要偏离 Divio 概述的简单文档风格。第一个考虑因素是用户和开发人员社区之间经常存在重叠。许多项目使用单独的系统记录开发人员和用户体验，但在此系统中同时考虑两者是合适的，并在适当的地方进行区分。因此，教程和操作指南将分为侧重于用户体验的“用户指南”和侧重于开发人员体验的“开发人员指南”。

下一个考虑因素是 TVM 社区内有一些特殊主题，可以从额外的关注中受益。可以创建特殊的“主题指南”来索引现有材料，并提供关于如何最有效地浏览该材料的背景信息。

为了方便新手，将制作一个特殊的“入门”部分，其中包含安装说明、为什么要使用 TVM 的概述以及其他首次体验文档。

技术细节 

我们使用 Sphinx 作为主要文档工具。Sphinx 支持 reStructuredText 和 markdown。如果可能，我们鼓励使用 reStructuredText，因为它具有更丰富的功能。请注意，Python 文档字符串和教程允许您嵌入 reStructuredText 语法。

有关构建文档的说明，请参阅 docs/README.md。

Python 参考文档 

我们使用 numpydoc 格式来记录函数和类。以下代码片段给出了一个文档字符串示例。我们始终记录所有公共函数，并在必要时提供我们支持的功能的用法示例（如下所示）。

def myfunction(arg1, arg2, arg3=3):
    """Briefly describe my function.

    Parameters
    ----------
    arg1 : Type1
        Description of arg1

    arg2 : Type2
        Description of arg2

    arg3 : Type3, optional
        Description of arg3

    Returns
    -------
    rv1 : RType1
        Description of return type one

    Examples
    --------
    .. code:: python

        # Example usage of myfunction
        x = myfunction(1, 2)
    """
    return rv1

请注意在文档的各个部分之间留空行。在上面的例子中，在 Parameters、Returns 和 Examples 之前必须有一个空行，以便正确构建文档。要向文档添加新函数，我们需要将 sphinx.autodoc 规则添加到 docs/reference/api/python）。您可以参考此文件夹下的现有文件，了解如何添加函数。

C++ 参考文档 

我们使用 doxygen 格式来记录 c++ 函数。以下代码片段显示了 c++ 文档字符串的示例。

/*!
 * \brief Description of my function
 * \param arg1 Description of arg1
 * \param arg2 Description of arg2
 * \returns describe return value
 */
int myfunction(int arg1, int arg2) {
  // When necessary, also add comment to clarify internal logics
}

除了记录函数用法外，我们还强烈建议贡献者添加关于代码逻辑的注释，以提高可读性。

Sphinx Gallery 操作指南 

我们使用 sphinx-gallery 来构建许多 Python 操作指南。您可以在 gallery 下找到源代码。值得注意的是，注释块是用 reStructuredText 而不是 markdown 编写的，因此请注意语法。

操作指南代码将在我们的构建服务器上运行，以生成文档页面。因此，我们可能会有限制，例如无法访问远程 Raspberry Pi，在这种情况下，请在教程中添加一个标志变量（例如 use_rasp），并允许用户通过更改一个标志轻松切换到真实设备。然后使用现有环境来演示用法。

如果您添加了操作指南的新分类，则需要在 conf.py 和操作指南索引中添加引用。

引用文档中的其他位置 

请使用 sphinx 的 :ref: 标记来引用同一文档中的其他位置。

.. _document-my-section-tag

My Section
----------

You can use :ref:`document-my-section-tag` to refer to My Section.

带有图像/图形的文档 

reStructuredText 的 figure 和 image 元素允许文档包含图像 URL。

为 TVM 文档创建的图像文件应位于 https://github.com/tlc-pack/web-data 存储库中，而使用这些图像的 .rst 文件应位于主 TVM 存储库 (https://github.com/apache/tvm) 中。

这将需要两个 Github Pull Request，一个用于图像文件，另一个用于 .rst 文件。贡献者和审阅者之间的讨论可能对于协调审查过程是必要的。

重要提示： 当使用上述两个 Pull Request 时，请在合并 https://github.com/tlc-pack/web-data 中的 Pull Request 之前，合并 https://github.com/apache/tvm 中的 Pull Request。这有助于确保 TVM 在线文档中的所有 URL 链接都有效。

文档

四种文档类型 

入门教程 