Axum documentation states `askama_axum` import is required, but it's not?

[jonkoops]

Hi, consider this as much a question as an issue report. I am quite new to the Rust ecosystem, so forgive me if this comes across as a tad ignorant. The documentation for the Axum integration states:

In your template definitions, replace askama::Template with askama_axum::Template.

However, when I have both askama and askama_axum installed, I can also use the 'regular' askama::Template without getting any compilation issues. For example:

use askama::Template;
use axum::{routing::get, Router};

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt::init();

    let app = Router::new().route("/", get(index));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();

    axum::serve(listener, app).await.unwrap();
}

#[derive(Template)]
#[template(path = "index.html")]
struct IndexTemplate {}

async fn index() -> IndexTemplate {
    IndexTemplate {}
}

Is this intended to work as such, and is it ok to keep using it like this? Why would one need to use asaka_axum and what extra does it do on top of the regular template?

I am also interested in how Cargo manages dependencies. If I install askama_axum I can see that askama is listed as a dependency, so I would expect that if I list askama_axum as the only dependency in Cargo.toml, it would also bring axum along.

However, if I modify the code above to use askama_axum::Template as the documentation states, and only install askama_axum, then I get the following compilation error:

error[E0433]: failed to resolve: could not find `askama` in the list of imported crates
  --> src/main.rs:14:10
   |
14 | #[derive(Template)]
   |          ^^^^^^^^ could not find `askama` in the list of imported crates
   |
   = note: this error originates in the derive macro `Template` (in Nightly builds, run with -Z macro-backtrace for more info)

This is strange because Template is imported from askama_axum and not askama. But it leads me to believe that I need to have both askama_axum and askama listed in Cargo.toml, even though my code does not directly depend on askama. Is this intentional behavior? Should I be listing both? If so, why is askama not pulled in with askama_axum?

Again, total novice here. Feel free to close this issue if it's too much of a hassle to answer. Thanks in advance.

[GuillaumeGomez]

@djc: Is it another issue with "the askama book is the not yet released version?". If so we should have a "nightly" and "stable" link for both, what do you think?

[jonkoops]

Another thing I noticed is that the example test file linked in the book also does not follow the recommendation of using the askama_axum package.

[djc]

@djc: Is it another issue with "the askama book is the not yet released version?". If so we should have a "nightly" and "stable" link for both, what do you think?

IIRC someone tried this and it introduced a lot of complexity (there's probably a closed PR somewhere), which I didn't like. If there's an efficient way (in terms of added code/complexity) to do it, would be okay -- but also this kind of disparity is pretty rare and it's not like we get a zillion issues from it.

[fcoury]

Just as some feedback I spent around 1h trying to figure out why I wasn't getting askama_axum::Template with askama 0.12 as the book recommends.

[joshka]

It seems like the underlying question didn't end up getting answered on this. Can some more context be provided to help users that are confused by the docs?

In 0.12.1, if a config.toml imports both askama and askama_axum, then askama_axum enables askama/with-axum, which in turn enables askama-derive/with-axum. askama_axum::Template is a re-export of askama::Template, so at least with the current released code, using askama::Template just works.

It sounds like this won't work in the future though - maybe?

Would it make sense to make the askama/with-axum feature flag import askama-axum? This would be similar to how many libs add behavior like this. Is there some blocker to this approach, or future plans that are not obvious here? Was this perhaps intended to help ensure that the version of the axum IntoResponse matches the version of axum to avoid version mismatches?

Edit: there's a bit of a subtle bug in the current situation. When the with-axum feature is enabled on askama, aksum-derive always generates the axum code, which requires askama-axum to be present. If you have a secondary crate without the askama-axum dependency, that crate will not compile correctly when with-axum is enabled in the main crate.

[djc]

The problem here is that the published documentation is for the main branch, which changed this.

[joshka]

There's still a bug though right?

[djc]

It's an issue. I don't think it is a bug that can be addressed in this project, though? That's just feature unification happening in your Cargo workspace, not much Askama can do about it.