If docs.rs can't build your project, what's the next best alternative? Is it hosting the docs in a gh-pages branch on GitHub? Can that be automated?
For my projects I tend to link to docs.rs as the "official" documentation, but then set up travis to generate docs and push them to GitHub Pages on every commit so you can also have "master" docs (mainly for people hacking on the project or those importing directly from git).
Here's an example of setting up travis to generate your documentation automatically. You're looking for the deploy
and before_deploy
sections in travis.yml
. Travis also have a page on using GitHub Pages as a "deployment" target.
where GitHub Pages + travis will work i find gitlab pages way more easy to setup.
All you need is a '.gitlab-ci.yml' with following content
image: "scorpil/rust:stable"
stages:
- test
- doc
- deploy
# Use cargo to test the project
test:stable:
stage: test
script:
- rustc --version && cargo --version # Print version info for debugging
- cargo test --verbose
- cargo build --features=cli
test:beta:
image: "scorpil/rust:beta"
stage: test
script:
- rustc --version && cargo --version # Print version info for debugging
- cargo test --verbose
- cargo build --features=cli
test:nightly:
image: "scorpil/rust:nightly"
stage: test
allow_failure: true
script:
- rustc --version && cargo --version # Print version info for debugging
- cargo test --verbose
- cargo build --features=cli
pages:
stage: doc
script:
- cargo doc
- mv target/doc public
- cp .ci/index.html public/index.html
artifacts:
paths:
- public
only:
- master
plus i have a manual 'index.html' as redirect to the index of my crate
<html>
<head>
<noscript><meta http-equiv="refresh" content="0; url=elf/index.html"></noscript>
</head>
<body onload="window.location = 'elf/index.html'">
<a href="elf/index.html">look here</a>
</body>
</html>
repository and docs
I agree, we use GitLab Pages at work and it's a lot less hassle than taking the Travis route.
I use GitHub pages but from the master branch docs folder.
So I generate the docs when checking in a new version with the code.
GitLab added support for CI on GitHub repositories literally a week after I asked this question. I hope that includes GitLab Pages!
Edit: It does!
Also checkout cargo release
. It automates the process of pushing docs to github pages every time you publish to crates.io.