executorch Documentation

Chapter: README (docs/README.md) Copy Section

ExecuTorch Documentation

Welcome to the ExecuTorch documentation! This README.md will provide an overview
of the ExecuTorch docs and its features, as well as instructions on how to
contribute and build locally.

All current documentation is located in the docs/source directory.

• Toolchain Overview
• Building Locally
• Using Custom Variables
• Including READMEs to the Documentation Build
• Contributing
• Adding Tutorials
• Auto-generated API documentation
  • Python APIs
  • C++ APIs

Toolchain Overview Copy Chapter

We are using sphinx with
myst_parser,
sphinx-gallery, and
sphinx_design in this
documentation set.

We support both .rst and .md files but prefer the content to be authored in
.md as much as possible.

Building Locally Copy Chapter

Documentation dependencies are stored in
.ci/docker/requirements-ci.txt.

To build the documentation locally:

1. Clone the ExecuTorch repo to your machine.

   bash Copy

   git clone -b viable/strict https://github.com/pytorch/executorch.git && cd executorch

2. If you don't have it already, start either a Python virtual environment:

   bash Copy

   python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip

   Or a Conda environment:

   bash Copy

   conda create -yn executorch python=3.10 && conda activate executorch

3. Install dependencies:

   bash Copy

   pip3 install -r ./.ci/docker/requirements-ci.txt

4. Run:

   bash Copy

   ./install_executorch.sh

5. Go to the docs/ directory.

6. Build the documentation set:

   text Copy

   make html

   This should build both documentation and tutorials. The build will be placed
   in the _build directory.

7. You can preview locally by using
   sphinx-serve. To install
   sphinx-serve, run: pip3 install sphinx-serve. To serve your documentation:

   text Copy

   sphinx-serve -b _build

   Open http://0.0.0.0:8081/ in your browser to preview your updated
   documentation.

Using Custom Variables Copy Chapter

You can use custom variables in your .md and .rst files. The variables take
their values from the files listed in the ./.ci/docker/ci_commit_pins/
directory. For example, to insert a variable that specifies the latest PyTorch
version, use the following syntax:

The current version of PyTorch is ${executorch_version:pytorch}.

This will result in the following output:

Right now we only support PyTorch version as custom variable, but will support others in the future.

You can use the variables in both regular text and code blocks.

Including READMEs to the Documentation Build Copy Chapter

You might want to include some of the README.md files from various directories
in this repository in your documentation build. To do that, create an .md
file and use the {include} directive to insert your .md files. Example:

```{include} ../README.md
```
/* Detailed source-code truncated for AI context efficiency. */

{include} ../path-to-your-file/outside-of-the-docs-dir.md

**NOTE:** Your tutorial source file needs to follow the tutorial template.

3. Add the file that you have created in **Step 1** to the `index.md` toctree
and add a `customcarditem` with the link to that file.

For example, if I wanted to include the `README.md` file from
`examples/selective_build` as a tutorial under
`pytorch.org/executorch/tutorials`, I could create a file called
`tutorials_source/selective-build-tutorial.md` and add the following to that
file:

In the index.md file, I would add tutorials/selective-build-tutorial in
both the toctree and the customcarditem sections.

Auto-generated API documentation

We use Sphinx to generate both Python and C++ documentation in the form of HTML
pages.

Python APIs Copy Section

We generate Python API documentation through Sphinx and sphinx.ext.autodoc.

The setup for Python documentation lies within source/. Sphinx uses the
conf.py configuration file where sphinx.ext.autodoc is configured as
extension. During the build, Sphinx generates the API documentation from the
docstrings defined in your Python files.

To define which API documentation to generate, you need to set up .rst files
that reference the modules you want to build documentation for. To auto-generate
APIs for a specific module, the automodule tag is needed to tell Sphinx what
specific module to document. For example, if we wanted a page to display
auto-generated documentation for everything in exir/__init__.py (relative to
the root of the repo), the RST file would look something like the following:

executorch.exir
=======================

.. automodule:: exir
   :members:
   :undoc-members:
   :show-inheritance:

These separate .rst files should all be linked together, with the initial
landing page under index.md.

C++ APIs Copy Section

Following Pytorch's way of generating C++ documentation, we generate C++ API
documentation through Doxygen, which is then converted into
Sphinx using
Breathe.

Specifically, we use Doxygen to generate C++ documentation in the form of XML
files, and through configs set in Sphinx's conf.py file, we use Breathe and
Exhale to use the XML files and generate RST files which are then used to
generate HTML files.

To configure Doxygen, we can run doxygen Doxyfile in the root of our
repository (ex. docs/source) which will generate a Doxyfile containing
configurations for generating c++ documentation. Specifically, the most
important/relevant parts are:

• OUTPUT_DIRECTORY specifies where to output the auto-generated XML files
• INPUT specifies which files to generate documenation for
• GENERATE_XML = YES

If you need to include new files, simply add them to the INPUT in the
Doxyfile. The generated output is included to the ExecuTorch documentation
build and referenced in index.md.