<mazgi.github.io 移行済>簡易な技術ドキュメントをHugoで書くと便利だった

この記事は以下に移行しました。

サンプルコードのドキュメントをHugoで書いてサンプルコードと一緒に配ったら便利そうだったのでやってみた。

やりたいこと

仕事で他社さんにサンプルコードとドキュメントをセットでお渡ししたいのだけど社ではGitHub Enterpriseを使っているのでリポジトリを直接見ていただくことが難しいケースがある。

規模が大きいプロジェクトならSphinx使うと(やる気次第で)いくらでも綺麗なドキュメントが書けそうではあるけど、規模がそれほどじゃないうちはサクッとMarkdownで書いて、でもソースコードとドキュメントが整合性取れててほしいという気持ちになる。
(今はSphinxもMarkdownで書けるそうだ、最近知った)

そもそも(私は)ドキュメント書きたくないので、できるだけスクリプトの提供やソースコードコメントで賄って文章量は最小限に抑えたいというモチベーションもあった。

そこで以下のような作戦を考えた。

さくせん

ドキュメントはHugoでプレビューしながらMarkdownで書く
生成したHTMLは /docs ディレクトリに突っ込む
社内向けにはGitHub PagesでmasterのHEADをホスティングする
社外向けには最新リリースのアーカイブを提供する

プレビューできるから書くの楽だし、tag打てるからソースコードとドキュメントの整合性も取りやすい。きっと便利！

できたもの

リポジトリはこちら。

github.com

GitHub Pagesはこちら。

Example Document with Hugo

テーマはこちらを使わせていただいた。
サイドバーでエントリが一覧できて技術ドキュメントらしさがある。

github.com

工夫

設定ファイルはこれ。

以下で生成した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 が見える。
アーカイブファイルにも展開後のディレクトリにもバージョンナンバーが含まれわかりやすい。

f:id:mazgi:20171207195147p:plain