本や記事を書く際、markdownやreSTで書くなど色々な書き方があると思う。 実際に何度かちょっとした記事を書いてみて、プログラムのコードを使った説明が多いような文章だと markdownやreSTにコピペするのがめんどくさいなぁというのがあった。
なのでJupyterNotebookで執筆できる環境を作ってみた。
GitHub - cocodrips/ipynb-writing
notebookディレクトリ直下に追加したnotebookに対して、以下の3つを行うしくみが実装してある。
- 仮想環境でpdfに変換
- 内容をhtmlにして自動デプロイ
- 文章/文字の校正を行う
機能の紹介
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上では以下のような感じでレビューが行える。
他の形式でもレビューできたらいいのだけど、残念ながら他のフォーマットには対応していない。
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にかけると、以下のように間違いを指摘される。
実際に書いていると間違った日本語や用語の表記をしてしまうことが多いので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でできるととても楽だなぁと思った。
皆様のおすすめの執筆環境・レビュー方法があればぜひ教えてください :)
