cargo-ghp-upload

用法

ghp-upload 的主要用途是为您的crate在github.io上提供构建后的文档。为此，您可以在 Travis 矩阵中至少包含以下内容

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

这将

• 在 master 分支的构建中
• 当构建不是由 PR 触发时
• 构建标准文档
• 并在 https://[用户].github.io/[仓库]/master 上发布。

这需要 Travis 有权访问您的仓库。最简单（且相对安全）的方法是创建一个具有 public_repoo 范围的 个人 API 访问令牌。然后在 Travis 上，定义安全的环境变量 GH_TOKEN，其值为新令牌。

如果您想提供更广泛的访问权限，您可以使用针对特定仓库的 部署密钥。如果没有提供令牌，脚本将使用 SSH 从仓库克隆并写入。Travis Pro 自动处理部署密钥，免费用户可以使用 Travis encrypt-file 加上一个脚本来将私钥移动到正确的位置。

这也意味着，只要您设置了 ssh，cargo ghp-upload 就可以在本地工作。分支和来源上下文是从 Git 而不是 CI 环境收集的。这意味着 cargo ghp-upload 也可以在 Travis 以外的 CI 上工作，但您目前必须手动防止它在 PR 构建上运行，如果您不希望它运行的话。

详细信息

当前这个包使用 ./target/ghp 作为临时空间。（未来可能会改变；请勿依赖。）不要修改此脚本之外的目录，否则可能会破坏功能。此包不会更改已上传目录的内容。

自定义

cargo-ghp-upload 0.3.2
CAD97 <cad97@cad97.com>
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]

ghp-upload 的强大之处在于可以从默认设置中进行进一步的定制。

ghp-upload 不会删除 如果它在部署分支上存在但不在已部署文件夹中的 [branch]/index.html。您可以使用此功能设置到适当的页面的重定向。

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

将上述文件作为 index.html 提交到 gh-pages 分支，它将保持存在。（使用 --remove-index 选项可退出此行为。）同样适用于根目录中不与分支文件夹冲突的任何内容。

使用 --branch 设置要上传的分支。请注意，如果您指定了任何明确的分支，则默认值将被覆盖，因此如果您想上传 master 和 next 的文档，请使用 --branch master --branch next。

使用 --directory 修改要发布到 GitHub Pages 的目录。这意味着您可以在该目录中构建任何结构，然后将其上传到您分支的文件夹中：使用 cargo doc 不同的配置到 ./target/doc 的子目录，或者将您的 mdbook 编译到 ./target/book 并将其上传到 GitHub Pages。或者两者都做，将它们合并到一个目录中，并在一个位置提供您的指南式和参考式文档！

稳定性

此项目遵循语义版本控制，扩展为 0.MAJOR.PATCH。（这是 cargo 实际使用的。）MAJOR 版本将根据 Rust RFC #1105 中定义的重大更改进行增加。MINOR 版本将根据 Rust RFC #1105 中定义的次要更改进行增加。所有其他更改都将按照语义版本控制规范中指定的进行。

由于这是一个仅包含二进制的分发，因此此稳定性仅适用于命令行参数的存在。新参数将是一个次要版本，删除或更改含义将是一个主要版本。

提高所需最低 Rust 版本是考虑为较小的破坏性更改，并在更改日志中注明。cargo-ghp-pages 将始终支持当前稳定版本以及至少两个之前的稳定版本。如果此滑动保证对于您的用例（如固定的 CI 构建）不足，我们建议使用 ~ 版本要求或固定确切版本。

当前最低 Rust 版本是 1.22.0。

许可证

根据您的选择，许可如下：

• Apache License，版本 2.0（《LICENSE-APACHE》或https://www.apache.org/licenses/LICENSE-2.0）
• MIT 许可证（《LICENSE-MIT》或https://opensource.org/licenses/MIT）

。

（注意，此二进制间接依赖于两个 WTFPL 许可的库。有关现有运动，请参阅TeXitoi/structopt#71 。）

贡献

除非您明确说明，否则任何提交以供包含在您的工作中的贡献（根据 Apache-2.0 许可证定义），均应如上所述双重许可，无需任何额外条款或条件。