search

djc / askama

Type-safe, compiled Jinja-like templates for Rust
Apache License 2.0
3.34k stars 215 forks source link

Documentation site shows unreleased features #720

Open natemcmaster opened 1 year ago

natemcmaster commented 1 year ago

There is gap between documented features in https://djc.github.io/askama/ and the actual behavior of the library when installing 0.11 (latest release on crates.io at time of writing.) Have you considered making it clearer which version is being documented?

Indicating more clearly the library version would help reduce confusion for new developers. For example, https://djc.github.io/askama/configuration.html documents a whitespace option in TOML config which doesn't work in 0.11. It took some digging to find the root cause. Root cause was that this feature was implemented in April (f997ba97bd298e219f3286fa792ec10874a34079) but hasn't been released yet.

Just a suggestion -- something like https://glebbahmutov.com/blog/versioned-doc-pages/ might help :) If this is something you would be open to but need help implementing, I could help.

By the way, this project is great! I look forward to the next release.

djc commented 1 year ago

I'm definitely open to better versioned documentation, but unlikely to get to implementing it myself, so your help would be much appreciated!

natemcmaster commented 1 year ago

Ok, here is a pull request which implements this. https://github.com/djc/askama/pull/726

Note: my source of inspiration was https://arctic-hen7.github.io/blog/dev/mdbook-versioning/ by @arctic-hen7

natemcmaster commented 1 year ago

So, I see #726 was rejected.

Can you give more specific guidance about what you would accept? I'm happy to help contribute, and I don't want to waste time trying to guess.

djc commented 1 year ago

Yes, sorry that I've changed my mind on this. I think there are mostly two things we can do: only deploy released book https://djc.github.io/askama/ and/or mention the version at which some feature was introduced in the documenation for that feature (though I don't think we should go through all the old features and do that).

natemcmaster commented 1 year ago

Ok. Both seem reasonable. The main motivation for me starting this thread was I thought the whitespace option in TOML was broken, but the real reason is that the feature hasn’t been released. Either option you suggested would have avoided the confusion.

avlec commented 1 year ago

0.11.2 is in the "book" and doesn't work as it's not published on crates.io

djc commented 12 months ago

Can you send a PR to fix it? Honestly in my mind it's not a big deal, these days I think it's okay to assume that people know how to add a library to their Cargo.toml.