Restructure ET documentation with 'Platform First' model #14720

psiddh · 2025-10-01T10:36:00Z

Summary

[PLEASE REMOVE] See CONTRIBUTING.md's Pull Requests for ExecuTorch PR guidelines.

[PLEASE REMOVE] If this PR closes an issue, please add a Fixes #<issue-id> line.

[PLEASE REMOVE] If this PR introduces a fix or feature that should be the upcoming release notes, please add a "Release notes: " label. For a list of available release notes labels, check out CONTRIBUTING.md's Pull Requests.

Test plan

[PLEASE REMOVE] How did you test this PR? Please write down any manual commands you used and note down tests that you have written if applicable.

pytorch-bot · 2025-10-01T10:36:04Z

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/14720

📄 Preview Python docs built from this PR

Note: Links to docs will display an error until the docs builds have been completed.

❌ 2 New Failures, 18 Pending

As of commit 7743abb with merge base d4d24ec ():

NEW FAILURES - The following jobs have failed:

pull / test-samsung-models-linux / linux-job (gh)
RuntimeError: Command docker exec -t 46e1a60dbb2acda297f4858366c8f4c07f6740a622f0809afbb870a1d10b9283 /exec failed with exit code 1
pull / test-vulkan-models-linux / linux-job (gh)
RuntimeError: Model validation failed: ExecuTorch outputs do not match reference model outputs

This comment was automatically generated by Dr. CI and updates every 15 minutes.

github-actions · 2025-10-01T10:36:43Z

This PR needs a `release notes:` label

If your change should be included in the release notes (i.e. would users of this library care about this change?), please use a label starting with release notes:. This helps us keep track and include your important work in the next release notes.

To add a label, you can comment to pytorchbot, for example
@pytorchbot label "release notes: none"

For more information, see
https://github.com/pytorch/pytorch/wiki/PyTorch-AutoLabel-Bot#why-categorize-for-release-notes-and-how-does-it-work.

mergennachin

See inline, thanks @psiddh for doing this

mergennachin · 2025-10-01T13:16:42Z

docs/source/index.md

 ### Documentation Navigation
-#### Introduction
+
+#### Getting Started


I don't like this is called "Getting Started"

Can we change to something like "Background", "Introduction", "Design and Architecture"?

mergennachin · 2025-10-01T13:19:31Z

docs/source/index.md

- [Troubleshooting](using-executorch-troubleshooting)
+- [Architecture & Components](getting-started-architecture)
+- [Core Concepts](concepts)
 - [Building from Source](using-executorch-building-from-source)


Can we have a section called

"Quick Start" that contains only a few sections

Getting Started

Model Export & Lowering

Building from Source

mergennachin · 2025-10-01T13:22:56Z

docs/source/index.md

+#### Fundamentals
+- [Model Export & Lowering](using-executorch-export)
+- [Runtime Architecture](runtime-overview)
+- [Memory Management](compiler-memory-planning)
+- [Performance Concepts](runtime-profiling)


This is a bit out of place. I'd say dissolve this section

I'd say move "Model Export & Lowering" to "Quick Start"

Runtime Architecture to the top section called (either "Background", "Introduction", "Design and Architecture").

Memory management and profiling can be in be either in Runtime or Advanced Topics.

Agree abt this section! The last two are already part of Advanced Topics, Removed this section completely

mergennachin · 2025-10-01T13:24:10Z

docs/source/index.md

+    - [CoreML (NPU/GPU - recommended)](backends-coreml)
+    - [MPS (GPU)](backends-mps)
+    - [XNNPACK (CPU)](backends-xnnpack)
+    - [Vulkan (GPU)](backends-vulkan)


Is Vulkan available on iOS??

Copy - paste error, removed

mergennachin · 2025-10-01T13:24:49Z

docs/source/index.md

+    - [XNNPACK (CPU)](backends-xnnpack)
+    - [Vulkan (GPU)](backends-vulkan)
+  ```
+- [Working with LLMs - iOS Examples](https://github.com/meta-pytorch/executorch-examples/tree/main/mv3/apple/ExecuTorchDemo)


This should point to LLM, not mv3

mergennachin · 2025-10-01T13:29:59Z

docs/source/index.md

+- [C++ Runtime Integration](using-executorch-cpp)
+- **Microcontrollers**
+  - [Cadence Xtensa Backend](backends-cadence)
+  - [ARM Ethos-U NPU Backend](backends-arm-ethos-u)


also Include this tutorial somewhere tutorial-arm-ethos-u.html https://docs.pytorch.org/executorch/1.0/tutorial-arm-ethos-u.html

On clicking backends-arm-ethos-u --> User would be able to discover [Arm Ethos-U Backend Tutorial]

(or) are you suggesting that Arm Ethos-U Backend Tutorial should be surfaced at the top

mergennachin · 2025-10-01T13:30:23Z

docs/source/index.md

+    - [Qualcomm AI Engine (NPU)](backends-qualcomm)
+    - [MediaTek (NPU)](backends-mediatek)
+    - [Samsung Exynos (NPU)](backends-samsung-exynos)
+  ```


Include Arm VGF

https://docs.pytorch.org/executorch/1.0/backends-arm-vgf.html

Where shall we include https://docs.pytorch.org/executorch/1.0/tutorial-arm-vgf.html

Added - ARM VGF Backend
On clicking this top link, it should take users to next page where [tutorial-arm-vgf.html] will be discovered.

Would this work ?

mergennachin · 2025-10-01T13:33:45Z

docs/source/android-section.md

+# Android
+
+## Quick Start & Integration
+[Getting started with ExecuTorch on Android](using-executorch-android)


When I click on it from here

https://docs-preview.pytorch.org/pytorch/executorch/14720/android-section.html

the left navigation disappears

https://docs-preview.pytorch.org/pytorch/executorch/14720/using-executorch-android.html

I need to look into it further.

mergennachin · 2025-10-01T13:37:02Z

docs/source/index.md


 ### Documentation Navigation
-#### Introduction
+


Do you want to list out all items individually?

How about we just list top-level categories?

I know that it predates you... I really don't like that we have a documentation sitemap on this page to begin with, we used to have something else before.

This is what I was thinking about too . Is this what you are thinking too roughly ? On the main landing page, we will have like 8 - 9 main sections / top categories ? I will put up another iteration of changes, just wanted to make sure

@psiddh

Yeah, top categories seems like a better as opposed to maintaining yet another site-map there with individual pages.

mergennachin · 2025-10-01T13:39:41Z

docs/source/android-section.md

+## Available Backends
+
+### CPU Backends
+- [XNNPACK Backend](backends-xnnpack) - Optimized CPU inference


When I click on this https://docs-preview.pytorch.org/pytorch/executorch/14720/backends-xnnpack.html it goes to iOS section.

abhinaykukkadapu · 2025-10-01T18:52:52Z

Sid, Thanks for the initiative to revamp the doc structure, couple of UX related comments:

Inconsistent sub sections in the landing page, there are collapsible sections on the top and only sub bullets in the bottom, not sure what you think about it.

Fundamentals section has "Learn More" hyperlinks, where as other pages just have direct hyperlinks to the heading

GregoryComer · 2025-10-01T21:31:36Z

Thanks! Here's my initial thoughts. I know you're iterating on a bunch of things, so feel free to ignore any of these that aren't relevant or if it's already planned.

The top nav bar seems to flow better on smaller screens (like my M1) with single-word titles. What do you think about changing maybe to Intro, Fundamentals, Android, iOS, Desktop, Embedded, Backends, LLMs?
(live)

(pr)

What do you think about folding the Using ExecuTorch on Android/iOS/etc. into the top-level Android pages, rather having them just as links? We can refactor out if they are too long. You might be planning this already, but basically have each landing page be a standalone quick start for that platform.
Thoughts on having a dedicated top-level section for model preparation/export? I saw you discussed changing the fundamentals section above. Maybe it could be converted into a model export section. Though under quick start might be good.
What about having a dedicated Installation page under Intro / Getting Started? I don't necessarily have a strong opinion on this, but I think it might be nice to split the current getting started into install and model prep.
Move C++ APIs docs from Laptop/Desktop to API section? We can link it from the relevant platforms.
Many style guides for docs recommend avoiding first person, including use of "Our" or "We". Should we try to adhere to that?

Overall, I like the platform-first layout. I saw there were a bunch of existing changes that you discussed with Mergen above, so I'm excited to see what the next revision will look like. I think we should focus on fleshing out the non-platform specific sections, getting started and model preparation.

mergennachin · 2025-10-02T13:46:04Z

Hi @psiddh

I am walking through the website via this link preview https://doc-previews.s3.us-east-1.amazonaws.com/pytorch/executorch/14720/index.html (the link commented by the bot was old -- so I looked at the log of "build (buck2) / Build doc" and found this link)

In the "Quick Start" category that contains "Getting Started", "Model Export & Lowering", "Building from Source" -- when you click on any of them pages, there's no left nav.
In the "Android" section landing page, "Quick Start & Integration" on the page and "Using ExecuTorch on Android" on the left nav, there's a title mismatch. Once you click on "Quick Start & Integration", it doesn't contain the left nav anymore.
"Integrating a Backend Delegate into ExecuTorch" (https://doc-previews.s3.us-east-1.amazonaws.com/pytorch/executorch/14720/backend-delegates-integration.html) shouldn't be in Embedded section

mergennachin · 2025-10-03T15:06:35Z

By the way, "https://docs-preview.pytorch.org/pytorch/executorch/14720/index.html" was still showing old cached result

Here's the trick I found

Ad ?v=1 (or anything), which forces to fetch new content

https://docs-preview.pytorch.org/pytorch/executorch/14720/index.html?v=1

mergennachin · 2025-10-03T15:09:45Z

docs/source/quick-start-section.md

+Follow these guides in order to get started with ExecuTorch:
+
+- **1. {doc}`getting-started`** - Initial Setup: Set up your development environment and run your first ExecuTorch example.
+


What about this page? https://docs.pytorch.org/executorch/stable/using-executorch-export.html

mergennachin · 2025-10-03T15:11:38Z

docs/source/quick-start-section.md

+
+## Prerequisites
+
+- Python 3.8+


Actually it's 3.10-3.12

mergennachin · 2025-10-03T15:11:52Z

docs/source/quick-start-section.md

+## Prerequisites
+
+- Python 3.8+
+- PyTorch 2.0+


PyTorch 2.9+ (it installs as depedency, so probably no need to explicitly mention). Otherwise, we have to book keep everytime

mergennachin · 2025-10-03T15:16:27Z

docs/source/platforms-desktop.md

+- [CoreML (recommended)](backends-coreml)
+- [MPS (Apple Silicon)](backends-mps)
+- [XNNPACK (CPU)](backends-xnnpack)
+- [Vulkan (GPU)](backends-vulkan)


Is it available natively on MacOS

mergennachin · 2025-10-03T15:18:17Z

docs/source/desktop-section.md

@@ -0,0 +1,19 @@
+(desktop-section)=


I think we can merging this landing page (desktop-section) and (platforms-desktop.md) page?

mergennachin · 2025-10-03T15:20:24Z

docs/source/embedded-section.md

@@ -0,0 +1,20 @@
+(embedded-section)=


And this page embedded-section.md and platforms-embedded.md pages

mergennachin · 2025-10-03T15:22:51Z

docs/source/platforms-embedded.md

+### Microcontrollers
+- [Cadence Xtensa Backend](backends-cadence)
+- [ARM Ethos-U NPU Backend](backends-arm-ethos-u)
+- [Custom Backend Development](backend-delegates-integration)


Why we have this section?

mergennachin · 2025-10-03T15:30:12Z

docs/source/embedded-backends.md

+embedded-cadence
+embedded-arm-ethos-u
+embedded-nxp
+backend-delegates-integration


backend-delegates-integration in embedded doesn't make sense. bring to "Backend Overview" section

mergennachin · 2025-10-06T14:14:24Z

Thank you @psiddh

Looks great

mergennachin · 2025-10-06T15:12:32Z

docs/source/index.md

+**🚀 Story 2**
+*One line for Story 2*
+
+[Click to read the complete details →](https://engineering.fb.com/2024/01/executorch-llama-mobile)


can you create a standalone landing page, so that I can start populating?

We can still keep the Story 1, Story 2 etc

digantdesai · 2025-10-06T19:26:34Z

docs/source/backends-overview.md

+
+## Learn More
+
+- [XNNPACK (Mobile CPU)](backends-xnnpack)


Suggested change

- [XNNPACK (Mobile CPU)](backends-xnnpack)

- [XNNPACK (CPU)](backends-xnnpack)

digantdesai · 2025-10-06T19:27:15Z

docs/source/backends-overview.md

+
+## Learn More
+
+- [XNNPACK (Mobile CPU)](backends-xnnpack)


Embed the links in the table?

digantdesai · 2025-10-06T19:28:34Z

docs/source/backends-overview.md

+| XNNPACK                | All                 | CPU           | General-purpose, fallback       |
+| Core ML                | iOS, macOS          | NPU/GPU       | Apple devices, high performance |
+| Metal Performance Shaders (MPS) | iOS, macOS | GPU           | Apple GPU acceleration          |
+| Vulkan                 | Android             | GPU           | Android GPU acceleration        |
+| Qualcomm NPU           | Android             | NPU           | Qualcomm SoCs                   |
+| MediaTek NPU           | Android             | NPU           | MediaTek SoCs                   |
+| ARM Ethos-U            | Embedded            | NPU           | ARM MCUs                        |
+| ARM VGF                | Android             | NPU           | ARM platforms                   |
+| OpenVINO               | Embedded            | CPU/GPU/NPU   | Intel  SoCs                     |
+| NXP NPU                | Embedded            | NPU           | NXP SoCs                        |
+| Cadence DSP            | Embedded            | DSP           | DSP-optimized workloads         |


Nit: remove NPU, DSP suffix from the first row?

digantdesai · 2025-10-06T19:30:17Z

docs/source/index.md

+
+---
+
+## 🎯 Recent Wins & Success Stories


Suggested change

## 🎯 Recent Wins & Success Stories

## 🎯 Wins & Success Stories

digantdesai · 2025-10-06T19:30:43Z

docs/source/index.md

+
+---
+
+### Documentation Sections


Drop this title

psiddh · 2025-10-06T20:00:18Z

@digantdesai Addressed all your comments

psiddh · 2025-10-06T22:41:40Z

@pytorchbot cherry-pick --onto release/1.0 -c docs

### Summary [PLEASE REMOVE] See [CONTRIBUTING.md's Pull Requests](https://github.com/pytorch/executorch/blob/main/CONTRIBUTING.md#pull-requests) for ExecuTorch PR guidelines. [PLEASE REMOVE] If this PR closes an issue, please add a `Fixes #<issue-id>` line. [PLEASE REMOVE] If this PR introduces a fix or feature that should be the upcoming release notes, please add a "Release notes: <area>" label. For a list of available release notes labels, check out [CONTRIBUTING.md's Pull Requests](https://github.com/pytorch/executorch/blob/main/CONTRIBUTING.md#pull-requests). ### Test plan [PLEASE REMOVE] How did you test this PR? Please write down any manual commands you used and note down tests that you have written if applicable. (cherry picked from commit 270873f)

pytorchbot · 2025-10-06T22:43:49Z

Cherry picking #14720

The cherry pick PR is at #14830 The following tracker issues are updated:

[v1.0.0] Release Tracker #14288 (comment)

Details for Dev Infra team

Raised by workflow job

psiddh requested a review from mergennachin as a code owner October 1, 2025 10:36

meta-cla bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Oct 1, 2025

mergennachin requested changes Oct 1, 2025

View reviewed changes

mergennachin requested review from GregoryComer and abhinaykukkadapu October 1, 2025 13:42

psiddh force-pushed the docs branch from d173f36 to 219b1aa Compare October 2, 2025 05:21

psiddh force-pushed the docs branch from 219b1aa to 0137e4c Compare October 3, 2025 03:47

mergennachin reviewed Oct 3, 2025

View reviewed changes

psiddh requested review from nil-is-all and svekars October 3, 2025 21:04

psiddh force-pushed the docs branch from 0137e4c to d3b956c Compare October 6, 2025 09:28

mergennachin approved these changes Oct 6, 2025

View reviewed changes

mergennachin reviewed Oct 6, 2025

View reviewed changes

psiddh force-pushed the docs branch 2 times, most recently from b7a03d0 to 117d2db Compare October 6, 2025 18:58

digantdesai reviewed Oct 6, 2025

View reviewed changes

docs/source/index.md Outdated

---

### Documentation Sections

Copy link

Contributor

digantdesai Oct 6, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop this title

psiddh force-pushed the docs branch from 117d2db to 1f53fed Compare October 6, 2025 19:59

psiddh requested a review from larryliu0820 October 6, 2025 20:03

psiddh requested review from JacobSzwejbka, lucylq, kirklandsign, Gasoonjia, SS-JIA and kimishpatel October 6, 2025 20:03

psiddh force-pushed the docs branch from 1f53fed to 481a0db Compare October 6, 2025 21:47

Restructure ET documentation with 'Platform First' model

7743abb

psiddh force-pushed the docs branch from 481a0db to 7743abb Compare October 6, 2025 21:56

GregoryComer approved these changes Oct 6, 2025

View reviewed changes

psiddh merged commit 270873f into pytorch:main Oct 6, 2025
128 of 130 checks passed

pytorchbot mentioned this pull request Oct 6, 2025

[v1.0.0] Release Tracker #14288

Open

mergennachin mentioned this pull request Oct 7, 2025

NXP backend: Fix missing NXP backend documentation page in release 1.0 documentation #14851

Closed

		Follow these guides in order to get started with ExecuTorch:

		- 1. {doc}`getting-started` - Initial Setup: Set up your development environment and run your first ExecuTorch example.

	- [XNNPACK (Mobile CPU)](backends-xnnpack)
	- [XNNPACK (CPU)](backends-xnnpack)

	## 🎯 Recent Wins & Success Stories
	## 🎯 Wins & Success Stories

Restructure ET documentation with 'Platform First' model #14720

Restructure ET documentation with 'Platform First' model #14720

Uh oh!

Conversation

psiddh commented Oct 1, 2025

Summary

Test plan

Uh oh!

pytorch-bot bot commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/14720

❌ 2 New Failures, 18 Pending

Uh oh!

github-actions bot commented Oct 1, 2025

This PR needs a release notes: label

Uh oh!

mergennachin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

psiddh Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

abhinaykukkadapu commented Oct 1, 2025

Uh oh!

GregoryComer commented Oct 1, 2025

Uh oh!

mergennachin commented Oct 2, 2025

Uh oh!

mergennachin commented Oct 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pytorch-bot bot commented Oct 1, 2025 •

edited

Loading

This PR needs a `release notes:` label

psiddh Oct 1, 2025 •

edited

Loading