--- tags: tauri-docs-2 --- # Rust Documentation & AST [Tauri Documentation Ecosystem Evolution meta issue on GitHub](https://github.com/tauri-apps/tauri-docs/issues/1040) ## TL;DR We've relied on docs.rs for documenting our Rust APIs and have just linked out to them where needed. We want to build our own in-house Rust documentation to be hosted on tauri.app. This will help solve the context switching between our website and docs.rs when in the middle of development. ## Current State & Community Feedback - Rust docs are hard to navigate (especially for Rust beginners) - Consistent format between JS, Rust, Config - Better hierarchy (dropdowns for a treeview to see an overview/outline of the API) - Rust documentation inline with guides instead of bouncing to docs.rs - Clearer link between JS and Rust docs - More examples ## Future State We'd like to host Rust documentation on tauri.apps to give us more flexibility in formatting as well as to allow references between Documentation and API references to be all on the same site. The Rust API reference should container the same **information** as docs.rs, but we should focus on a format and layout that is more accessible to those not quite as familiar to the Rust ecosystem. Note that design shouldn't be a main consideration for this stage. We should focus on the hierarchy and types of information presented and getting that all built out so that we can then iterate on design. ## High-Level Architecture - Run [`rustdoc-json`](https://rust-lang.github.io/rfcs/2963-rustdoc-json.html) within the source code repo to generate the AST in JSON format. - Note that unfortunately this only works on the Rust nightly toolchain. See the [PR here](https://github.com/rust-lang/rust/issues/76578). - We should be sure to lock to a specific nightly version in our CI pipeline to prevent random breaks happening - The RFC has high-level documentation for the format of the AST: https://rust-lang.github.io/rfcs/2963-rustdoc-json.html#reference-level-explanation - Use the generated JSON AST to pass to an Astro component and render out the pages. - The URL structure should be kept in mind for the route to the API docs: https://hackmd.io/@lorenzo-lewis/HyQLZrMFs#Summary-Structure - The mapping between modules, exports, macros, etc. should be similar to docs.rs. - We should have the ability to host different versions of the API - Keep in mind that to start with we'll probably on run this on [Tauri Core Rust code](https://github.com/tauri-apps/tauri/tree/dev/core/tauri) but that the idea is to re-use this for documenting other Rust code such as our official plugins and hosting that on the site. - A draft config that could be used to hold parameters for the metadata of a set of API documentation can be found here: https://hackmd.io/@lorenzo-lewis/HyQLZrMFs#Project-Mapping-Config