[Rust] GitLabでドキュメントを（非）公開

crates.io にクレートを公開すれば自動的に docs.rs でドキュメントをホストしてくれますが, 非公開クレートの場合 crates.io に出したくありません. このような場合, GitLab Pages を用いれば 関係者のみアクセス可能な状態 でドキュメントをホストすることができたので知見を共有します. なおすべて無料プランで可能です.

本記事の主要なアイデア (YAML の設定) はこちらのフォーラムの投稿に基づいています. 素晴らしい投稿に感謝です.

本論

https://gitlab.com は大雑把に言って GitHub のクローンサイトです. GitHub でできることはだいたいできます. GitHub Pages に相当する GitLab Pages というのもあります. そして GitHub Pages と異なり, GitLab Pages は GitLab のアカウントに基づいたアクセス制限を設けることができます. プライベートリポジトリの場合, デフォルトでそのリポジトリにアクセスする権限がある人しかそのページにアクセスできません (リポジトリ非公開のままページを一般に公開することもできるようです). これを利用すれば, 非公開クレートのドキュメントを手軽に関係者だけで共有することができます.

手順としては, 普通にプライベートリポジトリを作成してクローンしたら, Rust クレートを作成し, ドキュメントを頑張って書きます. そして次のような YAML ファイルを作成し CI/CD を設定します (テストも実行したいならばそれも設定します, 参考文献をご覧ください).

.gitlab-ci.yml

image: 'rust:latest'

stages:
  - doc

pages:
  stage: doc
  script:
    - cargo doc --no-deps
    - mv target/doc public
    - echo '<meta http-equiv="refresh" content="0; url={{CRATE NAME}}">' > public/index.html
  artifacts:
    paths:
      - public
  only:
    - master

ただし {{CRATE NAME}} を作成したクレートの名称に置き換えてください.

そして git push します. そうすれば自動的に CI が始まり, 完了すれば GitLab Pages でドキュメントがホストされます. ただし初回のみデプロイされるまでに30分程度の遅延があるようです (2回目以降は速やかにデプロイされます).

感想

事情があり GitLab で非公開プロジェクトを作成することになり, ドキュメントだけならば公開されても構わないんだけどと思いながらドキュメントをホストする方法を調べたら, 思いがけずアクセス制限つきでホストすることができてびっくりです. 結果的には GitLab でプロジェクト作成して大正解でした.

なお GitHub でも GitHub Actions を用いてドキュメント生成 & GitHub Pages へのデプロイを自動化することができるようです. が, 上でも述べたように GitHub Pages で公開されたものは誰でもアクセス可能になるようです (少なくとも現時点では).

参考文献

• https://users.rust-lang.org/t/my-gitlab-config-docs-tests/16396