この記事は以下に移行しました。
mazgi.log :: 簡易な技術ドキュメントをHugoで書くと便利だった
サンプルコードのドキュメントをHugoで書いてサンプルコードと一緒に配ったら便利そうだったのでやってみた。
やりたいこと
仕事で他社さんにサンプルコードとドキュメントをセットでお渡ししたいのだけど社ではGitHub Enterpriseを使っているのでリポジトリを直接見ていただくことが難しいケースがある。
規模が大きいプロジェクトならSphinx使うと(やる気次第で)いくらでも綺麗なドキュメントが書けそうではあるけど、規模がそれほどじゃないうちはサクッとMarkdownで書いて、でもソースコードとドキュメントが整合性取れててほしいという気持ちになる。
(今はSphinxもMarkdownで書けるそうだ、最近知った)
そもそも(私は)ドキュメント書きたくないので、できるだけスクリプトの提供やソースコードコメントで賄って文章量は最小限に抑えたいというモチベーションもあった。
そこで以下のような作戦を考えた。
さくせん
- ドキュメントはHugoでプレビューしながらMarkdownで書く
- 生成したHTMLは
/docs
ディレクトリに突っ込む - 社内向けにはGitHub PagesでmasterのHEADをホスティングする
- 社外向けには最新リリースのアーカイブを提供する
プレビューできるから書くの楽だし、tag打てるからソースコードとドキュメントの整合性も取りやすい。きっと便利!
できたもの
リポジトリはこちら。
GitHub Pagesはこちら。
テーマはこちらを使わせていただいた。
サイドバーでエントリが一覧できて技術ドキュメントらしさがある。
工夫
- 以下で生成したHTML内のリンクが
/
からの相対PATHになるふいんき(ちゃんと調べていない)baseURL = "/"
relativeURLs = true
uglyurls = true
- themeの指定
baseURL = "/" languageCode = "en-us" DefaultContentLanguage = "en" title = "Example Document with Hugo" publishDir = "../docs" relativeURLs = true uglyurls = true theme = "docdock" [params] themeVariant = "gray"
また、この設定ファイルとドキュメントのソースコード(Markdown他)を /docs.source
に置き、 publishDir = "../docs"
と設定することでリポジトリのrootにあまりファイルを置かないようにしている。
これはこのリポジトリにサンプルコードも同居する想定であり、rootにファイルが増えて見通しがわるくなることを避けるため。
HTMLを生成してcommitしてpushしてtagを打ったものがこちら。
Release v0.0.1 · mazgi/example-document-with-hugo · GitHub
アーカイブをダウンロードして手元で開くとこんな感じで index.html
が見える。
アーカイブファイルにも展開後のディレクトリにもバージョンナンバーが含まれわかりやすい。
index.html
もリンク先のドキュメントもブラウザで表示できる。便利。