cargo-ghp-upload

Usage

The main use-case for ghp-upload is providing built documentation for your crate on github.io. To do that, you can minimally include the following in your Travis matrix:

matrix:
  include:
  - env: GHP_UPLOAD_VERSION=0.3.2
    install:
    - cargo install --version $GHP_UPLOAD_VERSION cargo-ghp-upload
    script:
    - cargo doc --verbose && cargo ghp-upload -vv

and that will

• on builds for the master branch
• when the build is not triggered by a PR
• build the standard documentation
• and publish it at https://[user].github.io/[repository]/master.

This requires Travis to have write-access to your repository. The simplest (and reasonably secure) way to achieve this is to create a Persional API Access Token with public_repoo scope. Then on Travis, define the secure environment variable GH_TOKEN with the value being the new token.

If you want to provide more scoped access, you can use a deploy key for repo-specific access. If no token is provided, the script will use SSH to clone from and write to the repository. Travis Pro handles the deploy key automatically, and free users can use Travis encrypt-file plus a script to move the private key into the correct location.

This also means that cargo ghp-upload works locally so long as you have ssh set up for your account. Branch and origin context are collected from Git instead of the CI environment. This means that cargo ghp-upload will work on CI other than Travis, but you currently have to manually prevent it from running on PR builds if you don't wan't it to.

Details

This crate currently uses ./target/ghp as scratch space. (This may change in the future; do not rely on it.) Messing with the directory outside of this script could break things. This crate will not change the contents of the uploaded directory.

Customization

cargo-ghp-upload 0.3.2
CAD97 <[email protected]>
Upload documentation straight to GitHub Pages, maintaining branch separation and history

USAGE:
    cargo ghp-upload [FLAGS] [OPTIONS]

FLAGS:
        --remove-index    Remove `branch/index.html` if it exists
    -h, --help            Prints help information
    -r, --publish-tags    Publish documentation for tag builds (GitHub releases)
    -V, --version         Prints version information
    -v, --verbose         Enable more verbose logging [repeatable (max 4)]

OPTIONS:
        --deploy <deploy_branch>          The branch used for GitHub Pages [default: gh-pages]
        --message <message>               Message for the git commit [default: ghp-upload script]
        --branch <publish_branch>...      Branches to publish [default: master]
        --token <token>                   GitHub Personal Access token [default: $GH_TOKEN]
        --directory <upload_directory>    The directory to publish the files from [default: ./target/doc]

The power of ghp-upload comes from further customization from the default.

ghp-upload does not remove [branch]/index.html if it exists on the deploy branch but not the deployed folder. You can use this to set up a redirect to an appropriate page:

<meta http-equiv="refresh" content="0; url=my_crate/index.html">
<a href="my_crate/index.html">Redirect</a>

Commit the above file as an index.html to the gh-pages branch and it will stay present. (--remove-index opts out of this behavior.) The same goes for anything in the root that does not conflict with the branch folders.

Use --branch to set branches to upload for. Note that the default is overridden if you specify any explicit branches, so if you want to upload documentation for master and next, use --branch master --branch next.

Use --directory to change what directory is published to GitHub Pages. This means you can build whatever structure you want within that directory to upload to GitHub Pages in your branch's folder: cargo doc different configurations to subfolders of ./target/doc or compile your mdbook to ./target/book and upload those to GitHub Pages with history. Or do both, combine them into one directory, and serve your guide-style and reference-style docs in one location!

Stability

This project follows Semantic Versioning with the 0.MAJOR.PATCH extension. (This is effectively what cargo uses.) The MAJOR version will be incremented for major changes as defined in Rust RFC #1105 . The MINOR version will be incremented for minor changes as defined in Rust RFC #1105. All other changes will be as specified in the Semantic Versioning spec.

As this is a binary-only distribution, this stability only applies to the presence of command line arguments. New arguments will be a minor version, and removed or changed meaning will be a major version.

Upping the required minimum version of Rust is considered a minor breaking change, and will be noted in the changelog. cargo-ghp-pages will always support the current stable and at least two stable versions back. If this sliding guarantee is not enough for your use case (such as pinned CI builds), we recommend using a ~ version requirement or pinning the exact version.

The current minimum Rust version is 1.22.0.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

(Note that this binary transitively depends on two WTFPL-licensed libraries. See TeXitoi/structopt#71 for the existing movement to make this not an issue.)

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.