askama
askama copied to clipboard
djc
Documentation site shows unreleased features
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.
I'm definitely open to better versioned documentation, but unlikely to get to implementing it myself, so your help would be much appreciated!
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
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.
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).
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.
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.