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.

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

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

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

Or a Conda environment:

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

1. Install dependencies:

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

1. Run:

./install_executorch.sh

1. Go to the docs/ directory.

1. Build the documentation set:

make html

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

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

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:

<img src="source/_static/img/s_custom_variables_extension.png" width="300">

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:

/ Detailed source-code truncated for AI context efficiency. /

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:

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