Githubで書く電子書籍
JavaScript Promiseの本でのワークフロー
Markdown
- 外部ファイル読み込み機能が足りない
- pandoc ASTでMarkdown拡張書いた
- PDFとかキレイに作るのが面倒
- お手軽だが細かい事はいまいち
- => 今なら Leanpub や GitBook や Arturo.io がある
- 適当に始めるならMarkdownを選ぶのが間違いない
Sphinx(reST)
- AsciidocのRuby実装
- モダンな感じ - アイコンフォントがビルドインで使える
- デフォルトの出力でも十分キレイ
- => 採用
Pull Request駆動
Master から Branch を切るBranch を Pull Request するPull RequestをMasterにマージするMaster から gh-pages に自動的にデプロイする
Github Issueの活用
- Github Issueをメモ代わりにする
- Issue References便利
ref. #1
- 自分自身にPull Request駆動
feature/id/1
- 小さいチケットはPRしないで、コミットメッセージでIssueを閉じる
#fixes 1
- 詳しくは 一人で使えるGithub Issue
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing
semi-colons, etc)
- refactor: A code change that neither fixes a bug or adds a feature
- test: Adding missing tests
- chore: Changes to the build process or auxiliary tools and libraries such as documentation
generation
issue 171
pull-requestを含む
Travis CIの活用
- ビルド
- テスト - Pull Request駆動でやる意味の一つ
- デプロイ(masterへのコミットが対象)
ビルド
- AsciidoctorでHTMLを生成
- Asciidoc -> docbook -> pdfの生成
- ビルド時にWARNINGがでたらTravis CIはFAIL
テスト
- サンプルコードをテスト
- 出力したHTMLの内部リンクのテスト
<a href="#id"> がある時 <a name="id"> が存在するかをチェックする
- Asciidocのインラインコードをパーステスト
- asciidoc中に書かれたコードを抽出
- EsprimaでJavaScriptとしてパースできるかをテストする
- 詳細 => JavaScript Promiseの本 付録
デプロイ
- テスト済みのコミットのみが対象
- ビルドしたものをTravis CIからgithub-pagesにデプロイ
- Pull Requestに対してもHTMLを生成してプレビュー用URLの発行
- どのコミットに対してもプレビュー出来るURLを作れる
文章のリファクタリング
リファクタリングからが本番
- 文章表現の統一ルールは
CONTRIBUTEファイルに追加していく
- 一文が長くならないように気をつけて区切る
- typoは見つけたらその場でissueを立てる
- HTML版があるのでモバイルからも見られる + Issueを作れる
- 移動中にレビュー出来るようにする
Issueをモバイル環境でも作る
- 移動中にtypoを発見して修正のIssueを立てやすくする
- 後でまとめてIssueを処理する
Pull Requestしやすい空気
- 皆が慣れてるフォーマットで書く
- Asciidocで書いたけど、意外とPull Requestしてもらえた
- CONTRIBUTE.mdをちゃんと作る
- 成果物(HTML)をmasterに混ぜない
- 1文字Pull Request取り込む作業楽しい!
まとめ
- JavaScript Promiseの本 ではAsciidocを使った
- 人間はやることスグ忘れるのでGithub Issueにメモろう
- 自動化できるところは自動化してTravis CI等で回す
- 文章のリファクタリングは大変なので、周りが協力しやすい形にしよう
- ATOK買った方がいいと思いました
- typoのIssueが半分以上です