What's the best documentation solution other than docs.rs?

help
1

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?

1 Like
2

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.

3 Likes
3

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

1 Like
4

I agree, we use GitLab Pages at work and it's a lot less hassle than taking the Travis route.

5

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.

6

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!

7

Also checkout cargo release. It automates the process of pushing docs to github pages every time you publish to crates.io.

1 Like