### Chapter: README (docs/README.md) # 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](#toolchain-overview) - [Building Locally](#building-locally) - [Using Custom Variables](#using-custom-variables) - [Including READMEs to the Documentation Build](#including-readmes-to-the-documentation-build) - [Contributing](#contributing) - [Adding Tutorials](#adding-tutorials) - [Auto-generated API documentation](#auto-generated-api-documentation) - [Python APIs](#python-apis) - [C++ APIs](#c-apis) ## Toolchain Overview We are using [sphinx](https://www.sphinx-doc.org/en/master/) with [myst_parser](https://myst-parser.readthedocs.io/en/latest/), [sphinx-gallery](https://sphinx-gallery.github.io/stable/index.html), and [sphinx_design](https://sphinx-design.readthedocs.io/en/latest/) 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 Documentation dependencies are stored in [.ci/docker/requirements-ci.txt](https://github.com/pytorch/executorch/blob/main/.ci/docker/requirements-ci.txt). To build the documentation locally: 1. Clone the ExecuTorch repo to your machine. ```bash 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: ```bash python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip ``` Or a Conda environment: ```bash conda create -yn executorch python=3.10 && conda activate executorch ``` 1. Install dependencies: ```bash pip3 install -r ./.ci/docker/requirements-ci.txt ``` 1. Run: ```bash ./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](https://pypi.org/project/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 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 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: ```` ```{include} ../../../examples/selective_build/README.md ```` 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 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 Following Pytorch's way of generating C++ documentation, we generate C++ API documentation through Doxygen, which is then converted into [Sphinx](http://www.sphinx-doc.org/) using [Breathe](https://github.com/michaeljones/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`.