user guide: Add instructions for running `mdbook` in CI

This adds instructions for building and testing books in CI on every PR and
push, as well as instructions for how to automatically deploy to gh-pages on
successful CI runs on `master`.

Fixes #714
This commit is contained in:
Nick Fitzgerald 2018-06-22 10:30:06 -07:00
parent 2a55ff62f3
commit 488ace15ff
2 changed files with 56 additions and 0 deletions

View File

@ -17,6 +17,7 @@
- [Editor](format/theme/editor.md) - [Editor](format/theme/editor.md)
- [MathJax Support](format/mathjax.md) - [MathJax Support](format/mathjax.md)
- [mdBook specific features](format/mdbook.md) - [mdBook specific features](format/mdbook.md)
- [Continuous Integration](continuous-integration.md)
- [For Developers](for_developers/README.md) - [For Developers](for_developers/README.md)
- [Preprocessors](for_developers/preprocessors.md) - [Preprocessors](for_developers/preprocessors.md)
- [Alternate Backends](for_developers/backends.md) - [Alternate Backends](for_developers/backends.md)

View File

@ -0,0 +1,55 @@
# Running `mdbook` in Continuous Integration
While the following examples use Travis CI, their principles should
straightforwardly transfer to other continuous integration providers as well.
## Ensuring Your Book Builds and Tests Pass
Here is a sample Travis CI `.travis.yml` configuration that ensures `mdbook
build` and `mdbook test` run successfully. The key to fast CI turnaround times
is caching `mdbook` installs, so that you aren't compiling `mdbook` on every CI
run.
```yaml
language: rust
sudo: false
cache:
- cargo
rust:
- stable
before_script:
- (test -x $HOME/.cargo/bin/cargo-install-update || cargo install cargo-update)
- (test -x $HOME/.cargo/bin/mdbook || cargo install --vers "^0.1" mdbook)
- cargo install-update -a
script:
- cd path/to/mybook && mdbook build && mdbook test
```
## Deploying Your Book to GitHub Pages
Following these instructions will result in your book being published to GitHub
pages after a successful CI run on your repository's `master` branch.
First, create a new GitHub oauth token with the "public_repo" permissions (or
"repo" for private repositories). Go to your repository's Travis CI settings
page and add an environment variable named `GITHUB_TOKEN` that is marked secure
and *not* shown in the logs.
Then, add this snippet to your `.travis.yml`:
```yaml
deploy:
provider: pages
skip-cleanup: true
github-token: $GITHUB_TOKEN
local-dir: path/to/mybook/book
keep-history: false
on:
branch: master
```
That's it!