docs/contribute/document.rst - tvm - Git at Google


            
            ..  Licensed to the Apache Software Foundation (ASF) under one

            
                or more contributor license agreements.  See the NOTICE file

            
                distributed with this work for additional information

            
                regarding copyright ownership.  The ASF licenses this file

            
                to you under the Apache License, Version 2.0 (the

            
                "License"); you may not use this file except in compliance

            
                with the License.  You may obtain a copy of the License at


            ..    http://www.apache.org/licenses/LICENSE-2.0


            ..  Unless required by applicable law or agreed to in writing,

            
                software distributed under the License is distributed on an

            
                "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

            
                KIND, either express or implied.  See the License for the

            
                specific language governing permissions and limitations

            
                under the License.


            .. _doc_guide:


            Documentation

            
            =============


            .. contents::

            
              :depth: 2

            
              :local:


            TVM documentation loosely follows the `formal documentation style described by

            
            Divio <https://documentation.divio.com>`_. This system has been chosen because

            
            it is a "simple, comprehensive and nearly universally-applicable scheme. It is

            
            proven in practice across a wide variety of fields and applications."


            This document describes the organization of TVM documentation, and how to write

            
            new documentation. See `docs/README.md <https://github.com/apache/tvm/tree/main/docs#build-locally>`_

            
            for instructions on building the docs.


            The Four Document Types

            
            ***********************


            Introductory Tutorials

            
            ----------------------


            These are step by step guides to introduce new users to a project. An

            
            introductory tutorial is designed to get a user engaged with the software

            
            without necessarily explaining why the software works the way it does. Those

            
            explanations can be saved for other document types. An introductory tutorial

            
            focuses on a successful first experience. These are the most important docs to

            
            turning newcomers into new users and developers. A fully end-to-end

            
            tutorial — from installing TVM and supporting ML software, to creating and

            
            training a model, to compiling to different architectures — will give a new

            
            user the opportunity to use TVM in the most efficient way possible. A tutorial

            
            teaches a beginner something they need to know. This is in contrast with a

            
            how-to, which is meant to be an answer to a question that a user with some

            
            experience would ask.


            Tutorials need to be repeatable and reliable, because the lack of success means

            
            a user will look for other solutions.


            How-to Guides

            
            -------------


            These are step by step guides on how to solve particular problems. The user can

            
            ask meaningful questions, and the documents provide answers. An examples of

            
            this type of document might be, "how do I compile an optimized model for ARM

            
            architecture?" or "how do I compile and optimize a PyTorch model?" These

            
            documents should be open enough that a user could see how to apply it to a new

            
            use case. Practical usability is more important than completeness. The title

            
            should tell the user what problem the how-to is solving.


            How are tutorials different from how-tos? A tutorial is oriented towards the

            
            new developer, and focuses on successfully introducing them to the software and

            
            community. A how-to, in contrast, focuses on accomplishing a specific task

            
            within the context of basic understanding. A tutorial helps to on-board and

            
            assumes no prior knowledge. A how-to assumes minimum knowledge, and is meant to

            
            guide someone to accomplish a specific task.


            Reference

            
            ---------


            Reference documentation describes how the software is configured and operated.

            
            APIs, key functions, commands, and interfaces are all candidates for reference

            
            documentation. These are the technical manuals that let users build their own

            
            interfaces and programs. They are information oriented, focused on lists and

            
            descriptions. You can assume that the audience has a grasp on how the software

            
            works and is looking for specific answers to specific questions. Ideally, the

            
            reference documentation should have the same structure as the code base and be

            
            generated automatically as much as possible.


            Architecture Guides

            
            -------------------


            Architecture Guides are explanations are background material on a topic. These

            
            documents help to illuminate and understand the application environment. Why

            
            are things the way they are? What were the design decisions, what alternatives

            
            were considered, what are the RFCs describing the existing system? This

            
            includes academic papers and links to publications relevant to the software.

            
            Within these documents you can explore contradictory and conflicting position,

            
            and help the reader make sense of how and why the software was built the way it

            
            is. It's not the place for how-tos and descriptions on how to accomplish tasks.

            
            They instead focus on higher level concepts that help with the understanding of

            
            the project. Generally these are written by the architects and developers of

            
            the project, but can useful to help both users and developers to have a deeper

            
            understanding of why the software works the way it does, and how to contribute

            
            to it in ways that are consistent with the underlying design principles.


            Special considerations for TVM

            
            ------------------------------


            The TVM community has some special considerations that require deviation from

            
            the simple docs style outlined by Divio. The first consideration is that there

            
            is frequently overlap between the user and developer communities. Many projects

            
            document the developer and user experience with separate systems, but it is

            
            appropriate to consider both in this system, with differentiations where

            
            appropriate. As a result the tutorials and how-tos will be divided between

            
            "User Guides" that focus on the user experience, and "Developer Guides" that

            
            focus on the developer experience.


            The next consideration is that there are special topics within the TVM

            
            community that benefit from additional attention. Special "Topic Guides" can be

            
            created to index existing material, and provide context on how to navigate that

            
            material most effectively.


            To facilitate newcomers, a special "Getting Started" section with installation

            
            instructions, a overview of why to use TVM, and other first-experience

            
            documents will be produced.


            Technical Details

            
            *****************


            We use the `Sphinx <https://www.sphinx-doc.org>`_ for the main documentation.

            
            Sphinx supports both reStructuredText and markdown. When possible, we

            
            encourage reStructuredText as it has richer features. Note that the

            
            Python doc-string and tutorials allow you to embed reStructuredText syntax.


            See

            
            `docs/README.md <https://github.com/apache/tvm/tree/main/docs#build-locally>`_

            
            for instructions on building the docs.


            Python Reference Documentation

            
            ------------------------------


            We use the `numpydoc <https://numpydoc.readthedocs.io/en/latest/>`_ format to

            
            document the function and classes. The following snippet gives an example

            
            docstring. We always document all the public functions, and when necessary,

            
            provide a usage example of the features we support (as shown below).


            .. code:: python


                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


            Be careful to leave blank lines between sections of your documents. In the

            
            above case, there has to be a blank line before ``Parameters``, ``Returns`` and

            
            ``Examples`` in order for the doc to be built correctly. To add a new function to

            
            the docs, we need to add the `sphinx.autodoc

            
            <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ rules to

            
            `docs/reference/api/python <https://github.com/apache/tvm/tree/main/docs/reference/api/python>`_.

            
            You can refer to the existing files under this folder on how to add the

            
            functions.


            C++ Reference Documentation

            
            ---------------------------


            We use the doxygen format to document c++ functions. The following snippet

            
            shows an example of c++ docstring.


            .. code:: 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

            
                }


            Besides documenting function usages, we also highly recommend contributors to

            
            add comments about code logics to improve readability.


            Sphinx Gallery How-Tos

            
            ----------------------


            We use `sphinx-gallery <https://sphinx-gallery.github.io/>`_ to build many

            
            Python how-tos. You can find the source code under `docs/how_to/tutorials

            
            <https://github.com/apache/tvm/tree/main/docs/how_to/tutorials>`_.

            
            One thing that worth noting is that the comment blocks are written in

            
            reStructuredText instead of markdown so be aware of the syntax.


            The how-to code will run on our build server to generate the document page. So

            
            we may have a restriction like not being able to access a remote Raspberry Pi,

            
            in such case add a flag variable to the tutorial (e.g. ``use_rasp``) and allow

            
            users to easily switch to the real device by changing one flag. Then use the

            
            existing environment to demonstrate the usage.


            If you add a new categorization of how-to, you will need to add references to

            
            `conf.py <https://github.com/apache/tvm/tree/main/docs/conf.py>`_ and the

            
            `top-level docs index <https://github.com/apache/tvm/tree/main/docs/index.rst>`_

            
            (how-to entries are registered there directly, not in a separate how-to index).


            Refer to Another Location in the Document

            
            -----------------------------------------

            
            Please use sphinx's ``:ref:`` markup to refer to another location in the same doc.


            .. code-block:: rst


               .. _document-my-section-tag


               My Section

            
               ----------


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


            Documents with Images / Figures

            
            -------------------------------

            
            reStructuredText's `figure <https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure>`_

            
            and `image <https://docutils.sourceforge.io/docs/ref/rst/directives.html#image>`_

            
            elements allow a document to include an image URL.


            Image files created for TVM documentation should reside in the `<https://github.com/tlc-pack/web-data>`_

            
            repository, while the `.rst` files *using* those images should reside in the main TVM repostitory

            
            (`<https://github.com/apache/tvm>`_).


            This will require two GitHub Pull Requests, one for the image files and another for the `.rst` files.

            
            Discussion between the contributor and reviewers may be necessary to coordinate the review process.


            *IMPORTANT NOTE:* When using two Pull Requests as described above, please merge the

            
            Pull Request in `<https://github.com/tlc-pack/web-data>`_ *before* merging

            
            the Pull Request in `<https://github.com/apache/tvm>`_.

            
            This helps ensure that all URL links in TVM's online documentation are valid.
	.. Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	.. http://www.apache.org/licenses/LICENSE-2.0

	.. Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.

	.. _doc_guide:

	Documentation
	=============

	.. contents::
	:depth: 2
	:local:

	TVM documentation loosely follows the `formal documentation style described by
	Divio <https://documentation.divio.com>`_. This system has been chosen because
	it is a "simple, comprehensive and nearly universally-applicable scheme. It is
	proven in practice across a wide variety of fields and applications."

	This document describes the organization of TVM documentation, and how to write
	new documentation. See `docs/README.md <https://github.com/apache/tvm/tree/main/docs#build-locally>`_
	for instructions on building the docs.

	The Four Document Types
	***********************

	Introductory Tutorials
	----------------------

	These are step by step guides to introduce new users to a project. An
	introductory tutorial is designed to get a user engaged with the software
	without necessarily explaining why the software works the way it does. Those
	explanations can be saved for other document types. An introductory tutorial
	focuses on a successful first experience. These are the most important docs to
	turning newcomers into new users and developers. A fully end-to-end
	tutorial — from installing TVM and supporting ML software, to creating and
	training a model, to compiling to different architectures — will give a new
	user the opportunity to use TVM in the most efficient way possible. A tutorial
	teaches a beginner something they need to know. This is in contrast with a
	how-to, which is meant to be an answer to a question that a user with some
	experience would ask.

	Tutorials need to be repeatable and reliable, because the lack of success means
	a user will look for other solutions.

	How-to Guides
	-------------

	These are step by step guides on how to solve particular problems. The user can
	ask meaningful questions, and the documents provide answers. An examples of
	this type of document might be, "how do I compile an optimized model for ARM
	architecture?" or "how do I compile and optimize a PyTorch model?" These
	documents should be open enough that a user could see how to apply it to a new
	use case. Practical usability is more important than completeness. The title
	should tell the user what problem the how-to is solving.

	How are tutorials different from how-tos? A tutorial is oriented towards the
	new developer, and focuses on successfully introducing them to the software and
	community. A how-to, in contrast, focuses on accomplishing a specific task
	within the context of basic understanding. A tutorial helps to on-board and
	assumes no prior knowledge. A how-to assumes minimum knowledge, and is meant to
	guide someone to accomplish a specific task.

	Reference
	---------

	Reference documentation describes how the software is configured and operated.
	APIs, key functions, commands, and interfaces are all candidates for reference
	documentation. These are the technical manuals that let users build their own
	interfaces and programs. They are information oriented, focused on lists and
	descriptions. You can assume that the audience has a grasp on how the software
	works and is looking for specific answers to specific questions. Ideally, the
	reference documentation should have the same structure as the code base and be
	generated automatically as much as possible.

	Architecture Guides
	-------------------

	Architecture Guides are explanations are background material on a topic. These
	documents help to illuminate and understand the application environment. Why
	are things the way they are? What were the design decisions, what alternatives
	were considered, what are the RFCs describing the existing system? This
	includes academic papers and links to publications relevant to the software.
	Within these documents you can explore contradictory and conflicting position,
	and help the reader make sense of how and why the software was built the way it
	is. It's not the place for how-tos and descriptions on how to accomplish tasks.
	They instead focus on higher level concepts that help with the understanding of
	the project. Generally these are written by the architects and developers of
	the project, but can useful to help both users and developers to have a deeper
	understanding of why the software works the way it does, and how to contribute
	to it in ways that are consistent with the underlying design principles.

	Special considerations for TVM
	------------------------------

	The TVM community has some special considerations that require deviation from
	the simple docs style outlined by Divio. The first consideration is that there
	is frequently overlap between the user and developer communities. Many projects
	document the developer and user experience with separate systems, but it is
	appropriate to consider both in this system, with differentiations where
	appropriate. As a result the tutorials and how-tos will be divided between
	"User Guides" that focus on the user experience, and "Developer Guides" that
	focus on the developer experience.

	The next consideration is that there are special topics within the TVM
	community that benefit from additional attention. Special "Topic Guides" can be
	created to index existing material, and provide context on how to navigate that
	material most effectively.

	To facilitate newcomers, a special "Getting Started" section with installation
	instructions, a overview of why to use TVM, and other first-experience
	documents will be produced.


	Technical Details
	*****************

	We use the `Sphinx <https://www.sphinx-doc.org>`_ for the main documentation.
	Sphinx supports both reStructuredText and markdown. When possible, we
	encourage reStructuredText as it has richer features. Note that the
	Python doc-string and tutorials allow you to embed reStructuredText syntax.

	See
	`docs/README.md <https://github.com/apache/tvm/tree/main/docs#build-locally>`_
	for instructions on building the docs.


	Python Reference Documentation
	------------------------------

	We use the `numpydoc <https://numpydoc.readthedocs.io/en/latest/>`_ format to
	document the function and classes. The following snippet gives an example
	docstring. We always document all the public functions, and when necessary,
	provide a usage example of the features we support (as shown below).

	.. code:: python

	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

	Be careful to leave blank lines between sections of your documents. In the
	above case, there has to be a blank line before ``Parameters``, ``Returns`` and
	``Examples`` in order for the doc to be built correctly. To add a new function to
	the docs, we need to add the `sphinx.autodoc
	<https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ rules to
	`docs/reference/api/python <https://github.com/apache/tvm/tree/main/docs/reference/api/python>`_.
	You can refer to the existing files under this folder on how to add the
	functions.

	C++ Reference Documentation
	---------------------------

	We use the doxygen format to document c++ functions. The following snippet
	shows an example of c++ docstring.

	.. code:: 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
	}

	Besides documenting function usages, we also highly recommend contributors to
	add comments about code logics to improve readability.

	Sphinx Gallery How-Tos
	----------------------

	We use `sphinx-gallery <https://sphinx-gallery.github.io/>`_ to build many
	Python how-tos. You can find the source code under `docs/how_to/tutorials
	<https://github.com/apache/tvm/tree/main/docs/how_to/tutorials>`_.
	One thing that worth noting is that the comment blocks are written in
	reStructuredText instead of markdown so be aware of the syntax.

	The how-to code will run on our build server to generate the document page. So
	we may have a restriction like not being able to access a remote Raspberry Pi,
	in such case add a flag variable to the tutorial (e.g. ``use_rasp``) and allow
	users to easily switch to the real device by changing one flag. Then use the
	existing environment to demonstrate the usage.

	If you add a new categorization of how-to, you will need to add references to
	`conf.py <https://github.com/apache/tvm/tree/main/docs/conf.py>`_ and the
	`top-level docs index <https://github.com/apache/tvm/tree/main/docs/index.rst>`_
	(how-to entries are registered there directly, not in a separate how-to index).

	Refer to Another Location in the Document
	-----------------------------------------
	Please use sphinx's ``:ref:`` markup to refer to another location in the same doc.

	.. code-block:: rst

	.. _document-my-section-tag

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

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

	Documents with Images / Figures
	-------------------------------
	reStructuredText's `figure <https://docutils.sourceforge.io/docs/ref/rst/directives.html#figure>`_
	and `image <https://docutils.sourceforge.io/docs/ref/rst/directives.html#image>`_
	elements allow a document to include an image URL.

	Image files created for TVM documentation should reside in the `<https://github.com/tlc-pack/web-data>`_
	repository, while the `.rst` files using those images should reside in the main TVM repostitory
	(`<https://github.com/apache/tvm>`_).

	This will require two GitHub Pull Requests, one for the image files and another for the `.rst` files.
	Discussion between the contributor and reviewers may be necessary to coordinate the review process.

	IMPORTANT NOTE: When using two Pull Requests as described above, please merge the
	Pull Request in `<https://github.com/tlc-pack/web-data>`_ before merging
	the Pull Request in `<https://github.com/apache/tvm>`_.
	This helps ensure that all URL links in TVM's online documentation are valid.