Docs are built with an old pinned version of mdbook

[austinglaser]

This is causing rendering differences, as discussed in this book issue

[austinglaser]

I think there's some further discussion to be had here, about a couple of topics:

• How do we keep this consistent in the future? The CI scripts here are a source of duplication across all the rust-embedded books (and likely, to a greater or lesser extent, other documentation). This affects not just mdbook version, but other tools as well
  • The fact that mdbook got pinned to a specific version a while ago and only unpinned in a single place is testament to how easily these things can get out of sync
  • https://github.com/rust-embedded/book/blob/master/ci/install.sh always uses the latest, and has since before I started poking my nose in this particular area
  • https://github.com/rust-embedded/embedonomicon/blob/master/ci/install.sh does as well, though that change was merged recently
  • https://github.com/rust-embedded/debugonomicon/blob/master/ci/install.sh pins to the latest 0.x.y version, per feedback from @therealprof
• What should the mdbook pinning strategy be? Right now it's inconsistent. As I see it, we could:
  • Always take the latest
  • Pin to 0.x.y (does not protect from breaking mdbook changes, e.g. in a 0.4 series)
  • Pin to 0.3.x (does protect from breaking changes, but will require more frequent attention)

The first reasonable idea which occurs to me would be to have each book repo download a stub install.sh script from this repo. Books that need more tools to be installed (i.e. the embedonomicon) can wrap that stub to do that.

Whatever the decision, I'm happy to open a series of PRs to at minimum normalize this behavior. If there's consensus on a good way to keep this synchronized across multiple projects, I'm also happy to implement that.

CC @adamgreig, since you chimed in on one of the original issues here

[therealprof]

@austinglaser

Thanks for writing this up!

I'm not sure how the original mdbook decision came to be, maybe @japaric or @jamesmunns have more information about that.

Originally the mdbook version was freewheeling, we pinned v0.2.1 exactly for that reason and put reminders in place to undo it as soon as we can.

IMHO the most relevant questions are:

• Is the actually used version of mdbook relevant?
• Is it also relevant that all books are on the same version of mdbook? (And if so, how can we ensure that they're actually rebuilt when the version changes?)

Since the embedded book is linked on the rust-lang homepage, do we need to use the same version of mdbook they do for the rest of the documentation?

[austinglaser]

Is it also relevant that all books are on the same version of mdbook? (And if so, how can we ensure that they're actually rebuilt when the version changes?)

I believe so. Some of the confusion surrounding rust-embedded/book#212 resulted from two different versions (0.2.1 and 0.3.4) being used to render the book when hosted in two different places

Is it also relevant that all books are on the same version of mdbook? (And if so, how can we ensure that they're actually rebuilt when the version changes?)

I think enforcing this would at least simplify the above.

[jamesmunns]

Regarding the original decision:

• We used to use freewheeling, probably for no particularly good reason
• At some point, mdbook wasn't posting the build artifacts as part of their release. This caused the trust tool to get confused, as it expected the "latest published on crates.io" to == "latest artifacts published on github". This caused CI failures.
• Due to this, we then began pinning versions

Regarding harmony with the upstream Rust docs:

• Originally, we were the only users of mdbook 0.2.x, while older books were still on 0.1.x. I implemented a workaround to allow the upstream docs to build on EITHER 0.1 or 0.2 on a per-book basis
• Since then, I believe all books have been updated, and all are using a current version of mdbook, which is currently based on 0.3.x, currently 0.3.5 as of the time of this writing.

We should probably use whatever the upstream Rust project uses, unless we have a good reason, but I can't think of a good way to enforce this outside of curl | grep to get the version from this cargo.toml file, which seems... fragile.

[jamesmunns]

I also would not mind converging all of the books to a single git repo, to avoid duplication. This would have negative impact to our use of github pages as the base URL though.

[therealprof]

The pinning has been removed via #24.