Search code examples
documentationrustgithub-pagesrust-cargorustdoc

How to conveniently host a crate's up-to-date documentation?

I recently published my first crate on crates.io and I am wondering if I can maintain its documentation in an easier way.

Quite a few crates' docs are hosted on GitHub pages, so I thought I would give it a shot. I created a user.github.io repo, generated docs with cargo doc and pushed them to it. Everything worked just fine, the docs can be viewed from crates.io.

However, updating them is inconvenient; if I modify the crate's documentation, I need to:

  1. push these changes to the crate's repo
  2. generate updated docs via cargo doc
  3. move the docs' files to the GitHub page's folder
  4. push the docs to the documentation's repo

I'm pretty sure I'm not doing it right - especially point 3. What can I do to simplify this process? Is there any better way?

Solution

  • For many crates, Docs.rs is a good solution. It describes itself as:

    Docs.rs (formerly cratesfyi) is an open source project to host documentation of crates for the Rust Programming Language.

    Docs.rs automatically builds crates' documentation released on crates.io using the nightly release of the Rust compiler.

    This has tradeoffs:

    • Documentation is automatically generated and hosted for you, you don't even have to opt-in.
    • Documentation for each version of your crate is available.
    • If you have platform-specific conditional compilation, documentation for different platforms can be shown.
    • Only released versions of your crates will be documented. You can't publish a typo in the docs without a new release.
    • You are beholden to a third-party entity to continue providing this service.
    • You cannot (currently?) control what feature flags are used.

    Some people prefer to have more control over their documentation, or otherwise don't fall into the target audience for Docs.rs. Many of those cases choose to configure their CI infrastructure to generate the documentation and push the result somewhere.

    A common implementation of that is to use Travis CI and GitHub Pages as many projects already use these services. Any CI system and HTML hosting service can be used, so long as you are comfortable connecting the two.

    The general concept is:

    1. Add a step to build the documentation in CI.
    2. When a certain type of build is detected, push the generated documentation to the hosting service.
      • Possible choices for the type of build: any branch; master branch; a tag; etc.
      • Be careful to avoid exposing any credentials. A common mistake (that I have made myself) is to use a command like git push https://${GH_TOKEN}@github.com/.... If this command fails, the token is printed to stderr, exposing it to the world. Other less-obvious cases also expose the token on failure, so check those thoroughly.

    Some people have published blog posts detailing how they set things up. I have not verified that any of these are sane, but they may contain details to help you configure a specific solution.