rustdoc: Tracking issue for the Askama migration

[clubby789]

EDIT (2025-05-26): This is currently stuck as the original way it was done was making the code more complex (zulip). Before this can continue, it needs design work to make sure that having the templates in Askama is nicer than the current format! approach.

Tracking Issue for Rustdoc Askama Migration

Zulip Discussion

This issue is to track the progress of migrating rustdoc's HTML rendering to Askama.

Suggested Workflow

If you'd like to work on a component, please leave a comment claiming it so that work doesn't conflict.
Work on translating the current series of format!() and string building calls into an HTML template. Where possible, try to keep as much logic as possible on the Rust side. Make sure to refer to STYLE.md for templating style, especially using comment blocks to minimize whitespace.

A specific example of a migration (and some style considerations) is here.

Components to Migrate

• Sidebar (rustdoc: Migrate sidebar rendering to Askama #108784)
• Content
  • Stability/Portability/Deprecation (rustdoc: Migrate document_item_info to Askama #108757)
  • Item (print_item.rs)
    • Item Header
    • Doc Block
    • Modules
    • Functions
    • Traits
    • Structs
    • Unions (rustdoc: migrate item_union to an Askama template #109925)
    • Enums
    • Typedefs
    • Macros
    • ProcMacros (Migrate item_proc_macro to Askama #112031)
    • Primitives (Migrate item_primitive to Askama #112032)
    • Statics (bump minimum OS X version to 10.7 #11927)
    • Constants
    • Foreign Types (Migrate item_foreign_type to Askama  #112005)
    • Keywords
    • Opaque Types (Migrate item_opaque_ty to Askama #112034)
    • Trait Aliases (Migrate item_trait_alias to Askama #112030)
  • Scraped examples
• Source View
  • Line Numbers (Render source page layout with Askama #109187)
  • Code Highlighting

Implementation History

• Use Tera templates for rustdoc. #86157
• Move top part of print_item to Tera templates #89695
• Migrate rustdoc from Tera to Askama #92526

@rustbot label +T-rustdoc +A-rustdoc-ui

[jsha]

I'm working on fn assoc_method and fn inner_full_print.

[clubby789]

I'm working on fn print_src

[jsha]

As part of this, I'd like to get rid of struct Buffer and the f.alternate() method of emitting text instead of HTML.

Rationale: Using Formatter::alternate() to emit text instead of HTML was introduced to support line-wrapping function declarations over 80 characters. To this day, we only use f.alternate() when emitting function / method declarations, and we only care about the number of characters emitted.

Buffer was introduced as an alternative to f.alternate(): Instead of checking f.alternate() repeatedly throughout format.rs, the buffer itself could carry the information about whether we're outputting text or HTML. Removing the repeated checks of f.alternate() is a good goal - they significantly complicate format.rs. Also, Askama does not currently offer a way to access f.alternate() or format with {:#}, AFAICT. However, Buffer itself also doesn't compose well with Askama. Askama templates implement Display; ideally we would want a stack of structures, each potentially containing other structs that implement Display; then we can interpolate them directly into the parent template without excess allocations.

In the original PR adding f.alternate() support for the purpose of line wrapping, generating and then stripping HTML was considered and discarded. But I think it's the right solution here. Because we control the HTML and because we only care about counting the text output, we can get away with a very simplified HTML processor that knows how to strip tags and count entities (e.g. &) as a single character.

This is a summary of a similar comment I made on Zulip.

[jsha]

Update on the above: I missed a few places where we use {:#} and actually emit the plain output:

• In sidebar.rs, printing Methods from Deref<Target = Foo>, it's used to print the plain form of Deref and Foo.
• In sidebar.rs, printing the names of types under the various "Trait Implementations" sections.
• In render/mod.rs, it's part of how we generate the ids for internal linking to specific trait impls and for linking to the "Methods for Deref" section.
• In render/mod.rs, it's how we generate and refer to notable traits data in JSON storage.

I still think it makes sense to filter internally-generated HTML with a limited tag stripper, but it looks like we'll need to be able to actually emit the text rather than just count it, which means processing the entities (no big deal).

[djc]

FWIW, feel free to tag me in reviews if there are questions. Excited to see more usage of Askama in rustdoc!

As part of this, I'd like to get rid of struct Buffer and the f.alternate() method of emitting text instead of HTML.

As a potential point of interest, at work we have started using a very small procedural macro that effectively duplicates a template type to allow having two Templates wrapped around the same input type, one for plaintext and one for HTML. So this:

#[email(template = "contact-email")]
pub struct DomainContactEmail<'a> {
    pub domain: &'a str,
    pub sender: &'a ContactSender<'a>,
    pub message: &'a str,
    pub inbox_url: &'a str,
}

expands to this:

impl<'a: 'email, 'email> email::BodyTemplates<'email> for DomainContactEmail<'a> {
    type Text = DomainContactEmailText<'a, 'email>;
    type Html = DomainContactEmailHtml<'a, 'email>;
}
#[derive(askama::Template)]
#[template(path = "contact-email.txt")]
pub struct DomainContactEmailText<'a, 'email>(&'email DomainContactEmail<'a>);

impl<'a: 'email, 'email> From<&'email DomainContactEmail<'a>>
    for DomainContactEmailText<'a, 'email>
{
    fn from(email: &'email DomainContactEmail<'a>) -> Self {
        Self(email)
    }
}
impl<'a: 'email, 'email> std::ops::Deref for DomainContactEmailText<'a, 'email> {
    type Target = &'email DomainContactEmail<'a>;
    fn deref(&self) -> &Self::Target {
        &self.0
    }
}
#[derive(askama::Template)]
#[template(path = "contact-email.html")]
pub struct DomainContactEmailHtml<'a, 'email>(&'email DomainContactEmail<'a>);

impl<'a: 'email, 'email> std::ops::Deref for DomainContactEmailHtml<'a, 'email> {
    type Target = &'email DomainContactEmail<'a>;
    fn deref(&self) -> &Self::Target {
        &self.0
    }
}
impl<'a: 'email, 'email> From<&'email DomainContactEmail<'a>>
    for DomainContactEmailHtml<'a, 'email>
{
    fn from(email: &'email DomainContactEmail<'a>) -> Self {
        Self(email)
    }
}

Maybe this is used too much/duplicating the templates would be too much work for Rustdoc, just thought I'd mention it here as a point in the design space.

[jsha]

I'm working on changing primitive_link_fragment, href_relative_parts, and href_with_root_path to use a template to construct the hrefs with fewer allocations.

And thanks for the proc macro advice, and the kind offer of assistance, @djc!