# 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. 1. If you don't have it already, start a conda environment: ```{note} The below command generates a completely new environment and resets any existing dependencies. If you have an environment already, skip the `conda create` command. ``` ```bash conda create -yn executorch python=3.10.0 conda activate executorch ``` 1. Install dependencies: ```bash pip3 install -r ./.ci/docker/requirements-ci.txt ``` 1. Update submodules ```bash git submodule sync && git submodule update --init ``` 1. Run: ```bash bash install_requirements.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 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. ## Contributing Use the [PyTorch contributing guidelines](https://github.com/pytorch/pytorch/blob/main/CONTRIBUTING.md#writing-documentation) to contribute to the documentation. In addition to that, see [Markdown in Sphinx Tips and Tricks](https://pytorch.org/executorch/markdown-sphinx-tips-tricks.html) for tips on how to author high-quality markdown pages with Myst Parser. ## Adding Tutorials 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](https://github.com/pytorch/executorch/blob/main/docs/source/tutorials_source/template_tutorial.py) - [Markdown template](https://github.com/pytorch/executorch/blob/main/docs/source/tutorial-template.md) After creating a tutorial, make sure to add the corresponding path in the [index.rst](./source/index.rst) file in the following places: - In the [tutorials torctree](https://github.com/pytorch/executorch/blob/main/docs/source/index.rst?plain=1#L183) - In the [customcard section](https://github.com/pytorch/executorch/blob/main/docs/source/index.rst?plain=1#L201) 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. # 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.rst`. ### 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.rst`.