Augmented docs: a love letter to rustdoc and docs.rs

• Tooling

Docs are one of the superpower of Rust, thanks to the tooling and the central platform hosting them. Let’s take it to the next level! After a quick look at some of the most known features of rustdoc and docs.rs, we’ll review the guidelines and explore some of the advanced features available, like interacting with the #[doc] attribute directly or scraping examples. We’ll then look at how to enrich the docs with some crates from the ecosystem, like aquamarine for graphs, katex-doc for mathematical expression or document-features for automatic feature documentation, or with some templating, and see how far we can take it to have a complete documentation. To finish, we’ll dip our toes into documentation theory, through the Diátaxis framework and the Good Docs Project, check how rustdoc fit in those, and how other tools like mdbook or zola can complement it.