Publish multiple versions of the book

[drager]

💡 Feature description

Currently the docs are built only from master and published to https://rustwasm.github.io/wasm-pack/book/. This can cause users to think the latest version (0.5.1) contains all the features that are present in master but they aren't because master is currently not released. #462 is one example of this. It's also hard to check documentation for old releases.

I think the docs at https://rustwasm.github.io/wasm-pack/book/ should be generated for multiple versions (like docs.rs does), so we can have docs for master, latest stable as well as older releases.

What do you guys think?

[ashleygwilliams]

i love this idea. i - don't know the best way to set up the docs build process to do this, but it's something i certainly think would be a huge benefit.

[drager]

I have an idea how this could be done but I'm not sure it's the best approach though. I will try to explain what I'm thinking:

Since all releases are git tags and the book is published via Travis I was thinking that you could hook into the Travis pipeline somewhere around here and then iterate over all the available git tags that's outputted via git tag --list 'v*', do a git checkout for each tag and build the book to a new folder called all-docs or something.

This could possibly be accomplished by running something like the following command for master and for each tag outputted by the git tag command above:
cd docs && mdbook build --dest-dir "../all-docs/"$(git branch | grep \* | awk -F ' ' '{print $NF}' | sed 's/)//') && cd ..

This would result in one sub-folder per git tag in the all-docs folder. After that we need to add a index.html file that list's all the available books, so a table of contents.

The last step would be to publish all the contents of the all-docs folder to the gh-pages branch.

[drager]

I can try to see if I can get something working using the described approach above. Please let me know if anyone got any thoughts about this.

[drager]

I have made some progress on this and successfully been able to generate documentation for master, v0.5.0, v0.5.1 and v0.6.0 as well as a simple "table of contents".

I was first thinking that I could cover all the releases, from v0.1.0 to master but I noticed there's no docs checked in into the repo for tags from v0.1.0 to v0.4.2.

I think we need to discuss some things before proceeding further. What should we do for those releases that doesn't have any book-related files checked into the repo? Should we skip generating docs for all releases < v0.5.0 and just focus on v0.5.0 and newer?

[ashleygwilliams]

yeah, we just didn't have a book in those versions. i think focusing on 0.5.0 and later seems good, perhaps with a catch all page for previous versions that explains how to update your wasm-pack! we could also point to the docs.rs for those- tho those docs are really about the internals of wasm-pack that really shouldn't be something that an enduser would be terribly interested in.

[ashleygwilliams]

thanks so much for working on this and if you'd like- feel free to post a WIP pr and we can move the convo over there :) whichever you'd prefer tho!

[drager]

Great, thanks! Absolutely, I can post a PR :)

[alexcrichton]

FWIW I'm not actually sure if we want to do this. In theory older versions should become outdated very quickly to the point that we don't need to keep around documentation for them. Otherwise the main two versions that need documentation are the currently published version and whatever's on master. For that I'd personally love to see a central location for "published rustwasm books" in the book repo or similar, and that'd aggregate documentation for the game of life and currently published versions of wasm-pack and wasm-bindgen.

For master branch documentation I'd ideally prefer to leave that on gh-pages as it is today, but have a banner at the top saying it's nightly only with a link to the released documentation.

[danwilhelm]

I will point out too that many languages are plagued with having old documentation come up on Google searches. Rust being a prime example. Due to this, on each outdated doc page, I'd hope for a link to the same page in the most recent docs.

[ashleygwilliams]

i'm inclined to agree with @alexcrichton on this- it does seem that the two cases we would really want to support are current master and the latest version- this should greatly simplify the implementation tho- which is nice! @drager what do you think of that?

[drager]

I agree that @alexcrichton's solution is much better for solving issues like #462. It will be a lot easier to maintain and implement which I really like! Also, the point @danwilhelm brings up will be non-existent with this solution, which is great.

The only concern I have left is, what if some user is stuck with an old version of wasm-pack and are unable to upgrade, due to various reasons (maybe an older version of Rust or something). How should this be handled?

These older versions are present in git, via tags so that might be enough? Or maybe this is an issue for the future? I mean, it's probably not likely to be a problem right now, so maybe we shouldn't try to "solve" a problem that doesn't exist yet?

[alexcrichton]

I've pushed up rustwasm/rustwasm.github.io#37 which is my thinking about how we'd tackle this. I think for older documentation we'd stick to git for now

[drager]

Alright, sounds good.

[drager]

@alexcrichton @ashleygwilliams I think we can close this now since rustwasm/rustwasm.github.io#37 and a59cf6a#diff-e3e2a9bfd88566b05001b02a3f51d286 is merged?

[alexcrichton]

Indeed!