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:

• add the project to CircleCI,
• add read-write deploy key for GitHub and CircleCI, and

• push an initial gh-pages branch:

  git checkout --orphan
  git reset
  git commit --allow-empty -m 'initial commit'
  vi circle.yml # see below
  git push origin gh-pages
  

  where circle.yml is a dummy (so that the branch doesn’t give you test failures):

  test:
    override:
      - echo "noop"
  

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.