Skip to content

Latest commit

 

History

History
116 lines (71 loc) · 3.73 KB

README.md

File metadata and controls

116 lines (71 loc) · 3.73 KB

React Native ExecuTorch Documentation

This directory contains the source code for the documentation website of React Native ExecuTorch, built with Docusaurus.

Getting Started

Prerequisites

  • Node.js (v20+)
  • Yarn

Installation

Navigate to the docs directory and install dependencies:

cd docs
yarn install

Running Locally

Start the development server. Note: This command automatically generates the API reference from the TypeScript source before starting the site.

yarn start

The site will open at http://localhost:3000/react-native-executorch/.

Building

To build the static files for production:

yarn build

The output will be generated in the build/ directory.

Deployment

Using SSH:

$ USE_SSH=true yarn deploy

Not using SSH:

$ GIT_USER=<Your GitHub username> yarn deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

How API Reference Generation Works

We use docusaurus-plugin-typedoc to automatically generate documentation from the TypeScript source code.

  1. Source: The plugin reads ../packages/react-native-executorch/src/index.ts.

  2. Generation: On yarn start or yarn build, it generates Markdown files into docs/06-api-reference.

  3. Sidebar Integration: Docusaurus strips the number prefix (06-) from URLs but requires the folder name for configuration. We use a specific sidebar setup to ensure breadcrumbs work while keeping the UI clean.

Sidebar Configuration (sidebars.js)

The "API Reference" section is configured with specific settings to handle breadcrumbs correctly:

  • collapsed: true: Keeps the huge list of API files closed by default.

  • link property: Points to api-reference/index. This ensures clicking the text "API Reference" redirects to the Overview page.

  • items array: We nest the autogenerated items inside. This is critical because it creates the parent-child relationship needed for breadcrumbs (e.g., Home > API Reference > LLMType).

Troubleshooting Sidebar:

If you change the folder structure, ensure dirName matches the physical folder (06-api-reference), but id uses the Docusaurus ID (api-reference/index).

Releasing & Versioning

We use Docusaurus versioning to "freeze" documentation for older releases.

Creating a New Version

When you release a new npm version (e.g., 1.0.0), you must snapshot the documentation. Run this command from the docs/ folder:

yarn docs:version 1.0.0

Why is this important?

  1. It copies the current contents of docs/ (including the currently generated API reference) into versioned_docs/version-1.0.0.
  2. This ensures that if the TypeScript API changes in the future, the docs for v1.0.0 remain accurate to that version.

Working on "Next"

Edit files in docs/ as usual. These changes appear in the "Next" version of the site (the default view), reflecting the current main branch.

Troubleshooting

"Duplicate ID" Errors

If you see build errors about duplicate IDs, it usually means an old generation artifact is conflicting with a new one. Run:

yarn clear

This deletes the .docusaurus cache and build folder.

API Docs Not Updating

TypeDoc runs strictly at startup. If you modify comments in the TypeScript package:

  1. Stop the server.
  2. Run yarn start again to regenerate the Markdown files.

Showcase recording sources

showcase-sources.json records the devices, capture and editing details, fixture sources, and licenses for the task showcases. It is contributor metadata and is kept outside static/ so it is not published with the website.