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
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>
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!