rustdoc: use a templating engine to generate HTML · Issue #84419 · rust-lang/rust (original) (raw)

Right now rustdoc generates HTML with a series of writes embedded in the Rust code. This means the Rust code needs to process the elements of a page in the same order that they will be emitted in HTML. It makes it hard to get a holistic view of the page structure. It means we need to take care to make sure tags are balanced, which can be particularly hard when a function has multiple return points. It means in order to make any changes to the HTML, you need a good understanding of the Rust code.

If we use a templating engine, we can separate the templates from the Rust code, improving those problems. It would also mean we could have a mode for rustdoc to read templates at runtime instead of using its compiled-in templates. That would make iterating on HTML improvements easier, because we wouldn't have to wait for a compile cycle for each change.

There are a variety of templating engines out there, but I think mustache is quite good. In particular the choice to have no logic in templates is important, because otherwise it is tempting to put some logic in templates and some in the driving code, which becomes confusing. In Rust, the handlebars crate looks mature and actively maintained. It implements the handlebars template language, which is evidently different from mustache but pretty close.