Writing documentation for Turbopack

Turbopack has two main types of documentation. One is a description of the code and APIs, and the other is a high-level description of the overall behavior. Since there is no way to integrate with rustdoc yet, we deploy mdbook and rustdoc together with a script.

The source for the documentation is available at here.

Write a general overview document

Files written in markdown format in packages/next-swc/docs/src can be read by mdbook(Like the page you're looking at now). Our configuration includes mermaid support to include diagrams. See architecture how it looks like.

Write a rustdoc comment

If you write a documentation comment in your code, it will be included in the documentation generated by rustdoc. The full index can be found here, and individual packages can be read via https://turbopack-rust-docs.vercel.sh/rustdoc/${pkg_name}/index.html.

Build the documentation

The scripts/deploy-turbopack-docs.sh script bundles the mdbook and rustdoc and deploys them. You can use it locally as a build script because it won't run the deployment if it doesn't have a token. The script runs a rustdoc build followed by an mdbook build, and then copies the output of the rustdoc build under mdbook/rustdoc.

To locally build the documentation, ensure these are installed

• Rust compiler
• mdbook
• mdbook-mermaid

./scripts/deploy-turbopack-docs.sh
open ./target/mdbook/index.html

or

// note you can't check rustdoc links when running devserver
mdbook serve --dest-dir $(pwd)/target/mdbook ./packages/next-swc/docs