|0.3.4||Apr 10, 2018|
|0.3.2||Feb 19, 2018|
#96 in Cargo plugins
70 downloads per month
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
- when the build is not triggered by a PR
- build the standard documentation
- and publish it at
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
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.
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.
cargo-ghp-upload 0.3.2 CAD97 <firstname.lastname@example.org> 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.
--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
--branch master --branch next.
--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
./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!
This project follows Semantic Versioning with the
0.MAJOR.PATCH extension. (This is effectively what
MAJOR version will be incremented for major changes as defined in Rust RFC #1105
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.
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.)
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.