invoke cargo to install mdbook

[nikomatsakis]

cc @Michael-F-Bryan -- does this look right?

(I'm also not sure what the ~/.cargo/env command does, but it seemed likely it might be needed to run cargo, so I moved it up)

[nikomatsakis]

cc #1

[Michael-F-Bryan]

Thanks for picking up on this. I've always found that travis is annoying to get working just right, and it often takes me a couple commits to master to ensure the entire system works as intended.

[Michael-F-Bryan]

Oops! Looks like I must have messed up the order when copy/pasting across from .travis.yml files in other repositories.

[Michael-F-Bryan]

This makes sure ~/.cargo/bin is on our $PATH (its contents is just export PATH="$HOME/.cargo/bin:$PATH"). If we didn't make sure ~/.cargo/bin is on the $PATH we'd end up with command not found errors.

[Michael-F-Bryan]

You may want to wrap this in a if command -v ... block. To skip recompiling mdbook every time CI rins, you only want to install it if it isn't already installed. The if command -v foo bit returns 1 if the foo command isn't found and tends to be more reliable than using which foo.

[nikomatsakis]

OK :)

[Michael-F-Bryan]

I'm assuming you meant cargo install mdbook ... here, not cargo install cargo install ....

[nikomatsakis]

Uh, yeah =)

[Michael-F-Bryan]

If you change this to

cache:
- pip
- cargo

It'll let us cache both the ghp-import install and the mdbook install, as well as the cargo registry and cache in ~/.cargo so we don't need to re-download the world every time CI runs.

[nikomatsakis]

@Michael-F-Bryan take another look, if you please

[Michael-F-Bryan]

It looks good from what I can see, although the only real way to find out is to merge this PR into master and trigger uploading the rendered document.

To tell GitHub that Travis is allowed to push to GitHub Pages we'll also need to add an API key (with public_repo permissions) and then add the encrypted key to travis.yml.

[nikomatsakis]

@Michael-F-Bryan ok; where do I put the key in travis.yml exactly? It is under deploy, as I see here?

[nikomatsakis]

I feel like mdbook should have step-by-step instructions for this =)

[Michael-F-Bryan]

What I usually do is run travis encrypt GH_TOKEN=$TOKEN --add on the command-line and it'll add the token to travis.yml for you. It should end up looking something like this.

I feel like mdbook should have step-by-step instructions for this =)

I was thinking the exact same thing yesterday! Now that alternate backends have been merged into mdbook, I was thinking of making a backend which will automatically build your book and then push it up to GitHub Pages for you, printing detailed messages if anything is wrong with your environment. As part of that tool you'd mention how to set everything up in the README.

I've always found CI to be a massive pain to get set up, adding a bunch of noise to the git history because you'll typically need to make a commit to master push it up, wait 5-10 minutes for the build to fail, make a one-line change to see if you've fixed the issue, rinse and repeat. Appveyor is even worse because it only runs one build at a time for your entire project 😞

[nikomatsakis]

OK, well, I'm going to merge this. We'll see what happens I suppose.