Tobias Schottdorf    About    Archive    Feed

Rust and automatically generating docs on CircleCI

After some (private) dabbling around with Rust, I now have the first public toy project: hlc-rs, a hybrid logical clock.

I’m going to omit the customary ode of joy to the Rust language, tooling, and the community and only share a small snippet that I hacked together to automatically publish the auto-generated documentation via github pages after a successful master test run on CircleCI.

Step 1

I’m assuming the repository root is your crate’s root directory. I’m using this circle.yml:

dependencies:
  post:
    - git config --global user.email my@email.com
    - git config --global user.name "My Name"
    - curl -sf -L https://static.rust-lang.org/rustup.sh | sh /dev/stdin --channel=nightly --yes
test:
  override:
    - cargo test

deployment:
  docs:
    branch: master
    commands:
      - cargo doc && git fetch origin gh-pages && git checkout gh-pages && (git mv doc doc-$(git describe --always master^) || rm -rf doc) && mv target/doc/ ./doc && git add -A ./doc* && git commit -m 'update docs' && git push origin gh-pages

Pretty standard (also, likely suboptimal - but that’s fine for a project that doesn’t see a lot of traffic). The notable part is the last one:

# Generate the documentation.
cargo doc \
  && git fetch origin gh-pages \ # make sure we have the branch
  && git checkout gh-pages \     # check it out
  # If there's a `doc` directory, move it away or delete it if that fails.
  && (git mv doc doc-$(git describe --always master^) || rm -rf doc) \
  # Move the new docs in their place.
  && mv target/doc/ ./doc \
  # Add both the old docs and the new one.
  && git add -A ./doc* \
  # Commit, duh.
  && git commit -m 'update docs' \
  # Push new commit.
  && git push origin gh-pages

For setting this up, three simple steps are needed:

Of course, the same easily works on other CI platforms and possibly there are other ways to do it.

That’s it already! Now documentation like this should be auto-generated for you with the next CI run on master.