Add versioned book on readthedocs.org

[Kijewski]

This PR adds the file .readthedocs.yaml, which is used by readthedocs.org to generate the book on their servers. RTD can be used to easily host docs for every Askama version, so users can explore how to use the current stable version, the current HEAD, and an older version.

For older versions then the current PR, the books won't be built, because we did not provided the needed .readthedocs.yaml.

Also an index.hbs is added to made mdbook and RTD work better together. Only the left sidebar was changed, but you have to override the whole file to make changes.

You can preview the book on: https://test-askama-rtd.readthedocs.io/pr-rtd/.

Resolves #1030.
Fixes https://github.com/djc/askama/issues/720.

[GuillaumeGomez]

Just one question: can we generate it for older versions as well?

And also: we need to add a link to the book in the API documentation (at the crate level I suppose?).

[Kijewski]

Just one question: can we generate it for older versions as well?

Not really, not easily. You need a readthedocs.yaml file in the revision that you want to document. Readthedocs did allow to add the content of that file in a web form instead, but that feature was removed, for reproducibility's sake or something. They suggest that you create a branch v0.12.x.

I wouldn't like to add a branch just to document older releases, but maybe we could do a point release v0.12.2 that contains the file? But simply ignoring 0.12.x would would work for me, too. :)

[Kijewski]

@djc 👈🏻 👈🏻

It's not nice that only future versions will be documented, but I daresay that 0.13.0 won't be the last version, so better late than never?

[djc]

How was this generated? How do we keep it up to date in the future?

[Kijewski]

How was this generated?

I copied https://github.com/rust-lang/mdBook/blob/master/src/theme/index.hbs, and edited inside nav#sidebar.

How do we keep it up to date in the future?

I guess we can write a reminder somewhere to look into https://github.com/rust-lang/mdBook/commits/master/src/theme/index.hbs before tagging a new version?

[GuillaumeGomez]

Can we have a script to do it easily instead?

[Kijewski]

Added.

[djc]

Sorry -- I'd prefer for the script to be written in Rust.

[Kijewski]

Sure:

fn main() {
    if !std::process::Command::new("./update-theme.py")
        .spawn()
        .except("could not start")
        .status()
        .except("could not run")
        .success
    {
        panic!("script failed");
    }
}

:P Sorry, but feel free to translate the script.

[Kijewski]

Thinking more about it, it would also be possible not to commit index.hbs, but let RTD generate the file during the build process. After all, only they actually need the file. A local built or https://djc.github.io/askama/ as a beeding-edge version, can use the default index.hbs.

[djc]

Thinking more about it, it would also be possible not to commit index.hbs, but let RTD generate the file during the build process. After all, only they actually need the file. A local built or https://djc.github.io/askama/ as a beeding-edge version, can use the default index.hbs.

Sounds good to me.

[Kijewski]

So, yay or nay?

[djc]

Sorry, I don't want to merge this Python script. Happy to take the other improvements here, though.