JupyterNotebookでの技術書執筆環境を作った

Python

本や記事を書く際、markdownやreSTで書くなど色々な書き方があると思う。 実際に何度かちょっとした記事を書いてみて、プログラムのコードを使った説明が多いような文章だと markdownやreSTにコピペするのがめんどくさいなぁというのがあった。

なのでJupyterNotebookで執筆できる環境を作ってみた。

GitHub - cocodrips/ipynb-writing

notebookディレクトリ直下に追加したnotebookに対して、以下の3つを行うしくみが実装してある。

  • 仮想環境でpdfに変換
  • 内容をhtmlにして自動デプロイ
  • notebookの校正を行う

機能の紹介

dockerを使ってnotebookをpdf / htmlに変換する

htmlやmarkdownはともかく日本語で書かれたnotebookをpdfにexportするのはそこそこめんどくさい。 以下のコマンドでtexの環境をdocker上に作ってビルドしてくれる。

docker build -t ipybook . && docker run -v `pwd`/public:/book/public: -it ipybook make

出力サンプル:

以前本のレビューする際にdropboxのpdfレビューがとても便利だったので、定期的にビルドしたpdfをdropboxで共有するのがおすすめ。 dropbox上では以下のような感じでレビューが行える。

f:id:cocodrips:20171226232539p:plain

他の形式でもレビューできたらいいのだけど、残念ながら他のフォーマットには対応していない。

textlintで文字校正を行う

npmのtextlintを使って、技術用語の表記ゆれや読点のつけすぎ等を指摘する。
以下のコマンドでlintが走る。

docker build -t ipybook . && docker run -v `pwd`/public:/book/public: -it ipybook make textlint

いくつか技術書執筆に便利なルールを追加してあり、例えば ipynb-writing/chapter01-sample.ipynb のnotebookをlintにかけると、以下のように間違いを指摘される。

f:id:cocodrips:20171226233009p:plain

実際に書いていると間違った日本語や用語の表記をしてしまうことが多いのでtextlintは文章書くのが苦手な人には必須。

pdf/htmlの自動ビルド

このリポジトリをforkしてgitlabにpushすると、masterブランチにpushした際にCIが走ってhtml版・pdf版が自動デプロイされて以下のurlから確認とダウンロードができる。

http://{グループ名}.gitlab.io/{リポジトリ名}/

サンプル: http://cocodrips.gitlab.io/ipynb-writing/

GitLabは毎月2000分までPrivateリポジトリでもCIが無料で使えてすごい(ﾟдﾟ)太っ腹。

さいごに

今回はnotebookでの執筆を想定して環境を作ってみた。 latexをビルドする環境を作るのはめんどくさいので仮想環境 or CIでできるととても楽だなぁと思った。

皆様のおすすめの執筆環境・レビュー方法があればぜひ教えてください :)