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

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.

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

To build the documentation locally:

1. Clone the ExecuTorch repo to your machine.

2. If you don't have it already, start a conda environment:

   The below command generates a completely new environment and resets
   any existing dependencies. If you have an environment already, skip
   the `conda create` command.
   

   conda create -yn executorch python=3.10.0
   conda activate executorch

3. Install dependencies:

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

4. Update submodules

   git submodule sync && git submodule update --init

5. Run:

   bash install_executorch.sh

6. Go to the docs/ directory.

7. Build the documentation set:

   make html
   

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

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

   sphinx-serve -b _build
   

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

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.

You might want to include some of the README.md files from various directories in this repositories 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

NOTE: Many README.md files are written as placeholders with limited information provided. Some of that content you might want to keep in the repository rather than on the website. If you still want to add it, make sure to check the content for accuracy, structure, and overall quality.

Use the PyTorch contributing guidelines to contribute to the documentation.

In addition to that, see Markdown in Sphinx Tips and Tricks for tips on how to author high-quality markdown pages with Myst Parser.

You can add both interactive (.py) and non-interactive tutorials (.md) to this documentation. All tutorials should go to the tutorials_source/ directory. Use one of the following templates:

• Python Template
• Markdown template

After creating a tutorial, make sure to add the corresponding path in the index.rst file in the following places:

• In the tutorials torctree
• In the customcard section

If you want to include a Markdown tutorial that is stored in another directory outside of the docs/source directory, complete the following steps:

1. Create an .md file under source/tutorials_source. Name that file after your tutorial.

2. Include the following in that file:

   ```{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.rst 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:

```{include} ../../../examples/selective_build/README.md

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

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

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.rst.

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.rst.