Use Tera templates for rustdoc.

[jsha]

Replaces a format!() call in layout::render with a template
expansion. Introduces a templates field in SharedContext so parts
of rustdoc can share pre-rendered templates.

This currently builds in a copy of the single template available, like
with static files. However, future work can make this live-loadable with
a perma-unstable flag, to make rustdoc developers' work easier.

Part of #84419.

Demo at https://hoffman-andrews.com/rust/tera/std/string/struct.String.html.

[rust-highfive]

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez

[rust-highfive]

r? @GuillaumeGomez

(rust-highfive has picked a reviewer for you, use r? to override)

[jyn514]

Oh oof I forgot tera uses globwalk :( it's extremely slow: rust-lang/docs.rs@9c9647d

[jsha]

We don't actually use globwalk in this PR, we are manually loading files the same way the linked docs.rs PR does.

[GuillaumeGomez]

For now, I don't see much advantages to this change, but at least it's a good start. What about the size of generated files and performance comparison?

[jyn514]

@GuillaumeGomez the advantage is it's much easier to read than repeated write calls

[GuillaumeGomez]

In this case not really since only the big one has been moved.

[jsha]

It's true this is mainly an initial setup to make subsequent templatizations possible, and to give a feel for what the template language will feel like. And the one format call here is the most template-like thing we currently have, since it already has named fields for interpolation. But even in this initial change you can see some of the benefits in clarity and readability. Consider:

Old:

        logo = {
            if layout.logo.is_empty() {
                format!(
                    "<a href='{root}{path}index.html'>\
                     <div class='logo-container rust-logo'>\
                     <img src='{static_root_path}rust-logo{suffix}.png' alt='logo'></div></a>",
                    root = page.root_path,
                    path = ensure_trailing_slash(&layout.krate),
                    static_root_path = static_root_path,
                    suffix = page.resource_suffix
                )
            } else {
                format!(
                    "<a href='{root}{path}index.html'>\
                     <div class='logo-container'><img src='{logo}' alt='logo'></div></a>",
                    root = page.root_path,
                    path = ensure_trailing_slash(&layout.krate),
                    logo = layout.logo
                )
            }
        },

New:

<a href='{{page.root_path | safe}}{{krate_with_trailing_slash | safe}}index.html'>
    <div class='logo-container'>
    <img src='
        {%- if layout.logo -%}
        {{layout.logo}}
        {%- else -%}
        {{static_root_path | safe}}rust-logo{{page.resource_suffix}}.png
        {%- endif -%}
        ' alt='logo'>
    </div>
</a>

That's 20 lines vs 11 lines, and the 11 line version also removes some redundancy. Also, the HTML in the template version is easier to read without backslashes in front of all the quotes.

Performance: The difference so far will be quite negligible, because the amount of code moved in this PR is small. As we discussed in #84419, we may need to take a bit of a leap of faith performance-wise since the overall performance of templatizing everything won't be clear until we're much further along.

Byte size: struct.String.html is 54,713 bytes gzipped, vs 54,594 on master. Note that this branch doesn't have special treatment for removing excess whitespace. I used {%- and -%} where appropriate to take advantage of newline control, but the natural layout includes newlines and indents even between constant HTML elements, where there's no natural place for {%- and -%}. I think as a followup we should plan to pass the templatized content through a very basic parser that can remove HTML whitespace. If you'd like that as a prereq to landing this branch, let me know.

[GuillaumeGomez]

Byte size: struct.String.html is 54,713 bytes gzipped, vs 54,594 on master. Note that this branch doesn't have special treatment for removing excess whitespace. I used {%- and -%} where appropriate to take advantage of newline control, but the natural layout includes newlines and indents even between constant HTML elements, where there's no natural place for {%- and -%}. I think as a followup we should plan to pass the templatized content through a very basic parser that can remove HTML whitespace. If you'd like that as a prereq to landing this branch, let me know.

Yes please. I'm honestly very afraid of the whole "remove whitespaces from HTML". In this case, we even need to re-parse it. Even though I really like the whole templating idea, the downside is really worrying me. But I may be completely wrong. So I'd prefer to have the whitespaces removed from HTML before merging.

[jyn514]

@GuillaumeGomez are you worried about reparsing? or about the change in file size? If you're just worried about reparsing, I don't see why this has to be blocked on removing the whitespace.

[jsha]

Alright, with the latest updated, struct.String.html is 54,597 gzipped bytes, 2 bytes smaller than on master. :-)

No parsing required! The trick was to add {#- -#} to the end of each line. {# is a comment, and adding - triggers the whitespace removal path.

This is still not completely optimal, since it incentivizes putting a whole HTML tag on a single line, even when you might prefer to split out attributes on their own line. If you split out attributes on their own line, you're forced to choose between putting {#- -#} at the end of each line, which will concatenate the attributes and horribly break everything, or not putting any whitespace control in at all and incurring some extra bytes. Still, I think it's an okay tradeoff.

One thing that might be cool longer term is to see about getting Django's spaceless feature implemented in Tera (though I think we'd also want a special mode that's aware of HTML templates and collapses N whitespaces into 1 space character).

[jyn514]

One thing that might be cool longer term is to see about getting Django's spaceless feature implemented in Tera (though I think we'd also want a special mode that's aware of HTML templates and collapses N whitespaces into 1 space character).

That would be amazing! Can you open an issue on tera?

[jsha]

Done: Keats/tera#641

I also figured out how to do single whitespace for attributes: {# -#} instead of {#- -#} (that is, remove whitespace to the right, but not to the left). Switched to that, and added a STYLE.md discussing style for templates.

[GuillaumeGomez]

This is weird to have two different syntaxes depending if we're in a tag or not. Oh well...

[GuillaumeGomez]

Well, the final result is really not great if we have to add {# -#}/{#- -#} at every line... However if the end size is equal/smaller, then I won't block on this.

Let's just hope the "whitespace cleaner" feature will be implemented shortly in tera. :)

In any case, thanks a lot for working on this, it'll allow to improve the code a lot!

@bors: r=jyn514,GuillaumeGomez

[bors]

📌 Commit cd0f931 has been approved by jyn514,GuillaumeGomez

[bors]

⌛ Testing commit cd0f931 with merge 9d93819...

[bors]

☀️ Test successful - checks-actions
Approved by: jyn514,GuillaumeGomez
Pushing 9d93819 to master...