Merge #1035

1035: Add master branch docs build and publish r=matklad a=robojumper

Closes #1024.

Additional setup required: 

* The rust-analyzer travis repo needs an [environment variable](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings) `DOCS_TOKEN` that will be used to publish docs to the `gh-pages` branch. This is a GitHub access token with the appropriate permissions to push to this repository. Travis will keep this a secret.
* In the GitHub repository settings, the GitHub pages source needs to be set to the `gh-pages` branch. This option will only appear once a branch is created with this exact name -- created either through the `deploy` step or manually.
* In the GitHub repository settings, a GitHub pages theme will need to be chosen. What theme to use is unimportant, but [you must choose a theme](https://github.community/t5/GitHub-Pages/Github-Pages-are-not-published-after-following-the-documentation/m-p/18676#M1398).

Docs are built as part of any rust build (on linux and windows, though all my Travis windows builds have timed out), but only published on master builds on linux.

The docs badge links to `https://rust-analyzer.github.io/rust-analyzer/ra_ide_api/index.html` -- since this project is a cargo workspace, there isn't a global index page, hence just the link to an arbitrarily chosen crate. If this project had a canonical main crate with good documentation, one could link to that. All other crates are accessible through the sidebar.

Co-authored-by: robojumper <[email protected]>

1 files changed, 14 insertions, 0 deletions

diff --git a/.travis.yml b/.travis.yml
index 8d10a43f0..ebff7d8b0 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -12,12 +12,15 @@ build: &rust_build
         - rustup component add rust-src
         - cargo test --no-run  # let's measure compile time separately
         - cargo test
+        - cargo doc --all --no-deps
     env:
         - RUSTFLAGS="-D warnings", CARGO_INCREMENTAL=0
 
 matrix:
     include:
         - os: linux
+          before_script:
+              - DEPLOY_DOCS=1
           <<: *rust_build
         - language: node_js
           node_js: node
@@ -43,3 +46,14 @@ branches:
         - staging
         - master
         - trying
+
+deploy:
+    provider: pages
+    skip-cleanup: true
+    github-token: $DOCS_TOKEN  # Set in the settings page of your repository, as a secure variable
+    keep-history: true
+    local-dir: target/doc
+    branch: gh-pages
+    on:
+        branch: master
+        condition: $DEPLOY_DOCS = 1