概要

自動生成されるドキュメントをmasterとは別のブランチ上に配置し、GitHub Pagesで公開するための手順の覚え書き。

目的

masterブランチに影響を与えることなく、自動生成されるdocs/配下のデータのみをGitHub Pagesで公開する。

前提

GitHub Pagesの公開方法は3種類あるが、以下の理由からgh-pagesブランチを公開するものとした。

masterブランチを公開する
❌ 不要なデータを公開したくないのでNG。

ブランチのdocsフォルダを公開する
❌ .gitignoreに記述されているような、自動生成されるデータはmasterブランチから除外したいのでNG。

gh-pagesブランチを公開する
✅ 上記のいずれも当てはまらないため、消去法で採用。

手順

例としてReact+TypeScriptプロジェクトを新規作成し、ドキュメントをTypeDocで生成する場合の手順を示す。

プロジェクト作成

$ create-react-app docs-in-gh-pages --typescript
$ cd docs-in-gh-pages

リモートリポジトリ登録

GitHub上でリポジトリを作成し、プロジェクトのリモートリポジトリとして登録する。

$ git remote add origin git@github.com:hogehoge/docs-in-gh-pages.git
$ git push -u origin master

TypeDocインストール

TypeDocをインストール後、ドキュメントを生成してリモートリポジトリへプッシュする。

$ yarn add -D typedoc
$ echo docs/ >> .gitignore # 1.
$ git add .
$ git commit -m "Installed: TypeDoc"
$ git push

ドキュメントの出力先であるdocs/をリポジトリから除外する。

参照リポジトリ

GitHub Pagesへの公開

docs/を公開

GitHub Pagesの公開方法が未設定の状態でgh-pagesブランチが作成されると、自動的にgh-pagesブランチ上のデータが公開されるため、docs/をgh-pagesブランチへプッシュしてドキュメントを公開する。

$ git checkout -b gh-pages # 1.
$ node node_modules/.bin/typedoc --out docs src
$ touch docs/.nojekyll # 2.
$ git add docs --force # 3.
$ git commit -m "First docs' commit"
$ git subtree push --prefix docs origin gh-pages # 4.

-bオプションにより、カレントブランチを基準にブランチを新規作成する。
GitHub Pagesはページをjekyllで処理して公開するのだが、ファイル名が_から始まるファイルはjekyllの仕様で公開されない。TypeDocが生成するほとんどのファイルは_から始まるので、jekyllの処理をスキップするため.nojekyllを配置する。
.gitignoreにdocs/が記述されているため、--forceオプションを付けて強制的にステージングする。
origin/gh-pagesブランチが存在しないので、新たに作成される。

参照リポジトリ

事後処理

docs/を公開した後のローカルブランチgh-pagesは不要なため、削除する。

$ git checkout master
$ git branch -D gh-pages

ドキュメントの更新

masterブランチ上でコミットが進んでから、ドキュメントを更新してGitHub Pagesに反映する手順を示す。

masterブランチ上でのコミット

例として、以下のファイルを作成してコミットする。

typedoc.json

{
  "exclude": [
    "src/index.tsx",
    "src/serviceWorker.ts",
    "src/**/*.test.tsx"
  ]
}

$ git add .
$ git commit -m "Update: some files have excluded"
$ git push

参照リポジトリ

ドキュメント更新

masterブランチ上の作業に伴ってドキュメントを更新する。手順はdocsを公開とほぼ同じだが、ローカルのgh-pagesをorigin/gh-pagesブランチと同期するため、git subtree addコマンドを用いること。

この例ではTypeDocの仕様によりgit subtree addにて取得したdoc/を削除している。削除するデータをわざわざ取得するのは冗長に思えるが、git subtree addはgh-pagesブランチへの追跡を行うため必ず実行されなければならない。

$ git checkout -b gh-pages
$ git subtree add --prefix docs origin gh-pages # 1.
$ rm -rf docs # 2.
$ node node_modules/.bin/typedoc --out docs src
$ touch docs/.nojekyll
$ git add docs --force
$ git commit -m "Second docs' commit"
$ git subtree push --prefix docs origin gh-pages

docs/が既に存在する場合はエラーになるため、あらかじめ削除しておくこと。
出力先ディレクトリが既存かつ、TypeDocが生成しうるファイル以外のもの（この場合は.nojekyll）が存在するとTypeDocがエラーを起こすため、出力先ディレクトリを削除して後続のコマンドでドキュメントを再作成する。

参照リポジトリ

考察

git subtreeコマンドが有効に働き、スマートに目的を達成できた。TypeDocの仕様により.nojekyllを毎回作成するのは手間だが、シェルやCIのスクリプトを用いて自動化すれば負担にならないだろう。