[RFC] Sphinx and the Documentation Refactor

Development pre-RFC
#1

Overview

Documentation is one of the pieces of TVM that we would like to improve in the near future. Currently, much of our documentation is tutorial-focused, but we would like to add several new types of documentation in the future. The Documentation Refactor RFC from July proposes four types of documentation:

  • Introductory Tutorials: Practical documents that are most helpful in helping new users learn the software.
  • How-to Guides: Practical documents that are most helpful in getting work done.
  • References: Advanced documents that are most helpful in getting work done
  • Deep Dives: Advanced documents that are most helpful in learning they why’s of the software.

An open question is where these should live in the Sphinx doctree. This RFC proposes an organization and seeks feedback from the community.

Landing Pages

Additionally, there is some need for another class of document: a landing page, which is useful to give 10,000-foot explanations of large subjects or describe how components interoperate. The closest example we have to this now is the VTA page, under Misc. We expect to add these sparingly, but we think they will serve as an important top-level directory page for large topics and for TVM verticals.

Also, there are often times in tutorials or other lower-level documentation when it would be helpful to reference a concise definition of a large component (i.e. TIR). A top-level TVM Components landing page can serve both as a directory and a glossary.

We expect to have:

  • A TVM Components overview page, which groups TVM components by subject area, briefly defines them and their relationship with others, and links out to tutorials for each component
  • A Deploy and Integration landing page, which is just exactly the page we have now. This anticipates further content development here.
  • A Developer Guide landing page, which describes the different categories of developer documentation in the TVM Docs page and links out to them
  • A ”TVM landing page, which describes the project and its components, and links out to tutorials and design docs.
  • A VTA page, which is as is checked-in now.

Tutorial Reorganization

This RFC proposes we reorganize the tutorials according to subject area, and add content describing the grouping at the toctree root. Here is an example tutorial subsection:

  • Import Models ← Add content here
    • Compile Caffe2 Models
    • Compile CoreML Models
    • Compile Keras Models
    • Compile MXNet Models
    • Compile ONNX Models
    • Compile PyTorch Models
    • Compile TensorFlow Models
    • Compile TFLite Models
    • Compile YOLO-V2 and V3 in DarkNet

Each tutorial in this section demonstrates how to import a model, and some of them also verify the imported Relay model against the original framework. At the end of this process, the user is left with a Relay model plus some parameters. This higher-level pattern isn’t currently explained anywhere—the reader has to deduce it by reading multiple tutorials. This task is especially challenging for users new to ML, such as deployment engineers.

In this example, a brief high-level explanation belongs in the Import Models page at the root of this tutorial category.

Therefore, the root toctree element of each tutorial section should bring the user to a page or subsection that motivates the grouping based on the following questions:

  • Briefly, what do these tutorials do?
  • Why would you want to do these things?
  • If these tutorials describe a common piece of TVM (i.e. Tensor Expression), what is that thing and how does it relate to the compilation process?
  • If these tutorials describe a common process, what is that process? What is the user left with at the end of it? Where do they go next?

These descriptions should emphasize brevity so as not to erect too much of a barrier between tutorial groups. They can always link out to landing pages or design docs for a bigger picture with more description about the relationship between this piece of TVM and others.

Toctree Organization

Before I give the full proposed toctree, let’s first look at a generic toctree that demonstrates the proposed layout:

  • Getting Started
    • Installation
    • Getting Started Tutorial (a high-level How-To Guide)
    • Landing pages (until we have more than a few)
  • Tutorials
    • How-to Guides
  • Design Docs
    • Deep Dives
  • References
    • References
  • Misc
    • FAQ
    • Index

Proposed Toctree

4 Likes
TVM Monthly - January 2024
#2

As part of the start of this reorganization process, I’ve sent up a patch to create a “Getting Started With TVM” tutorial. It moves and updates some existing documents, organizing them into a narrative that guides the user through the motivations for using TVM, then starts at TE and works up through Auto Scheduling to demonstrate how to work with the various parts of TVM.

This is a fairly large effort, including some new material. If those with time can take a moment to read over the patch and leave comments, that would be very helpful. Anything ranging from making sure terminology is correct, to improvements to code, additions, and corrections are all appreciated. Thanks in advance to everyone for helping to land this first major part of the documentation refactor.