文档

TVM文档大致遵循Divio提出的正式文档风格。选择这一体系是因为它"简单、全面且几乎普遍适用。经过各种领域和应用的实践验证。"

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

这些是逐步引导新用户熟悉项目的指南。入门教程旨在让用户快速上手软件，而不必解释软件为何如此运作，这些解释可以留待其他文档类型说明。入门教程专注于提供成功的首次体验，是将新人转变为新用户和开发者的最重要文档。一个完整的端到端教程——从安装TVM和支持的机器学习软件，到创建和训练模型，再到编译到不同架构——将让新用户有机会以最高效的方式使用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语法，请注意语法差异。

操作指南代码将在我们的构建服务器上运行以生成文档页面。因此我们可能会有一些限制，比如无法访问远程树莓派设备，在这种情况下可以向教程添加一个标志变量（例如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文件。贡献者和审阅者之间可能需要讨论以协调审查流程。

重要提示： 当按照上述方式使用两个拉取请求时，请先合并https://github.com/tlc-pack/web-data中的拉取请求，然后再合并https://github.com/apache/tvm中的拉取请求。这有助于确保TVM在线文档中的所有URL链接都是有效的。

文档

四种文档类型 

入门教程 