簡易な技術ドキュメントをHugoで書くと便利だった

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

gohugo.io

やりたいこと

仕事で他社さんにサンプルコードとドキュメントをセットでお渡ししたいのだけど社では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

index.html もリンク先のドキュメントもブラウザで表示できる。便利。

f:id:mazgi:20171207195157p:plain

EC2 P3で使えるChainerMN入りのDockerイメージを作った

sonots先生によるこの記事をやってみたという話です。

qiita.com

概要

Dockerfileはここにあります。

github.com

ベースはNVIDIAさんのオフィシャルイメージです。

https://hub.docker.com/r/nvidia/cuda/

実行結果

ChainerMNのexampleを試した結果はこちら。
今のところシングルNodeシングルGPUとシングルNodeマルチGPUしか試してないです。

gist.github.com

手順はこちらの通りなんですが時間が取れていない...

docker (nvidia-docker) を使ってマルチノードで ChainerMN を実行する方法(仮) - Qiita

P3じゃなくても動くはずですが、ホスト側にGPUとnvidia-dockerは必要です。
今回は社の環境で試したのでsonots便利先生環境の恩恵を受けてます🙏

blog.livedoor.jp

イチから構築する場合はこういう記事が参考になりそう。

chie8842.hatenablog.com

経緯とか

めでたく記事も出たので色々言えるようになったのですが、実はありがたいことにP3の先行検証というのをさせていただいてました。
(なおイベント当日はカメラマンしてました)

engineer.dena.jp

この検証時点ではChainerMNではなくChainerで、環境もVM上に直接作ってたのですが、その後部内から「Dockerイメージになってたほうが便利」とフィードバックいただき先行者の記事を参考に手探りしてる状況です。
私はMLわからないマンなのですが、最初 cuDNN 7 + CuPy 1.0.3 で環境作ろうとしてバージョンが合わなくてどうしよ!と思ってたら「今日 cuDNN 7 対応の CuPy 2.0 リリースするよ!」と教えていただいたりとか、この業界本当に数時間単位で進歩しててすごい。

こういう用途だとコンテナほんと便利なんですけど、でもDockerイメージの命名むずかしい。
mazgi/cuda-cv:9.0-cudnn7-devel-ubuntu16.04 じゃなくて、
mazgi/cuda-cv-9.0-cudnn7-devel-ubuntu16.04:latest とかにしたほうがいいのかな(長い)。
そもそもの話としては実質Chainer & ChainerMNイメージなのでそういう名前にすべきだし(さらに長くなる)。

Adobe CCのライセンスを別のPCに移す方法(ライセンス認証解除→再認証)

Adobe CCが不要なPCの認証を解除して、使いたいPCで何かしらのアプリを起動すれば認証されて使えるようになる。
PC買い替えなどのタイミングで必要になるが、そういうときは大体ライセンス認証解除の手順を忘れているのでメモ。

手順

認証解除の手順を3行で。
なお認証解除はWeb上での操作なので、使うPCはなんでもいい(はず)。

  1. https://accounts.adobe.com/plansを開く
  2. 「プランを管理」をクリック
  3. 「ライセンス認証したデバイス」から不要な方のデバイスを削除

ここまでできれば、あとはAdobe CCを使いたいPCでPhotoshopやIllustratorなどのアプリを起動すれば認証され使えるようになる。

f:id:mazgi:20170212015541p:plain

f:id:mazgi:20170212015557p:plain

ちゃんとAdobeのヘルプに書いてあるのだが、公式ドキュメントなので「ライセンス認証とは?」やスタンドアローン版の説明も併記されていて文量が多いので簡単にまとめてみた。

helpx.adobe.com

Hadoop黙々会を始めました

@usaturnさんと一緒に「Hadoop黙々会」を始めました。 hadoop-bootup.connpass.com 私の思惑としては「エンジニアたる者、何歳になっても学び続けないとね。でも機会を作らないとなかなか集中して学べないので人を巻き込んでイベントにしてしまおう!」といったところです。

Read more

NISSAN×DeNA @ dots. #23x に行ってきました

追記

当日のツイートをTogetterにまとめさせていただきました! togetter.com


dots.さんで「NISSAN×DeNA 車は、モノ<プロダクト>なのか、コト<サービス>なのか。当事者たちから見える風景を語る。」というイベントが開催されたので「えっ?日産の方とDeNAの方がDeep Learningや機械学習について語るの!?」と分かりやすく興味喚起されて伺ってきました!

eventdots.jp

ハッシュタグ#23xで当日のツイートが一覧できます。
(言語を日本語にした方が見やすいかもしれません)

Read more

【SELECK掲載記念】AnsibleでPartitionを切る!

追記

さくらのクラウドについて取材していただいた記事も公開されました!
合わせてご覧ください!!

さくらのクラウドで「尖ったインフラ環境」を構築。カスタマイズに強い、その実力とは | SELECK


本編

先日「SELECK(セレック)」様にAnsibleの活用事例をインタビューいただきました。

seleck.cc

素晴らしい記事にしていただいたのでせっかくなら何かネタになりそうな実例をご紹介したいと考えた結果(?)、バッドノウハウが詰まったパーティションの切り方をご紹介したいと思います!

Read more

RackTablesで個人ネットワークを管理する

個人で使っているさくらのクラウドアカウントでサーバーやスイッチが増えてしまいどれが何やら分からなくなってきたのでRackTablesで管理しようと思い(立ってからだいぶ時間が)たちました。

f:id:mazgi:20160715064627p:plain

ようやく重い腰を上げてRackTablesを運用し始めたのでメモしておきます。

Read more