Software Designの原稿をJupyter NotebookとiPad Proで書いた話

雑誌 Software Designさんから執筆依頼を頂いた。「Visual Studio Code の Jupyter Notebook実行機能を使ってPythonのテキスト処理などを学べる記事を」ということで、得意なテーマだしスケジュールに余裕のある時期でもあったので、けっこう気軽に引き受けさせていただいた。

この記事は、プログラミング初心者が雑誌を見ながらコードを一文字づつJupyter Notebookに写経して実行する、という読み方を念頭に執筆した。なので、文章を読みながら出てきたコードを入力し、Shift+Enter で実行できるように留意している。そこで、記事文章もJupyter NotebookのMarkdownセルで執筆し、解説とコードと実行結果をすべて Jupter Notebookだけで管理してみた。

せっかくVSCodeとJupyter NotebookをPythonのフロントエンドとして、という企画なので、執筆もVSCode上のJupyter Notebookでやろうと思ったが、現在のバージョンではMarkdownセルを編集中に別のセルに移動すると入力した文字が消えてしまう、という致命的な問題があり、断念した。

執筆手順

解説の文章とサンプルコードの執筆については、特に語ることはない。普通にMarkdownセルに文章を書き、Pythonセルにコードを書いて、実行結果を出力するだけだ。

普通にreStructuredTextやMarkdownなどのマークアップだけで書いていると、サンプルコードや実行結果を原稿にコピーするのは結構な手間だが、Jupyter Notebookでは当然その作業は不要だ。記事の執筆そのものはサクサク進み、かなりのスピードで書き上げることができた。

図の作成

今回は、記事にかなり多めに図を入れさせていただいた。初心者向けの記事であり、文章ではわかりにくいことも、図示すればけっこうわかりやすかったりする。今回は正規表現の解説も行ったが、経験上、正規表現のパターンマッチングをうまく理解できない人でも、ちょっと絵を書いてあげるとすんなり納得してくれることが多い。

とはいえ、私が図をきれいに書いていると、とても時間がかかってしまう。どうせ編集部の方で清書していただけるのだから、手書きでサクッとかきあげ、入稿させた頂いた。図は iPad Pro+Apple Pencilに、Notabilityというアプリで描いた。Notabilityは作画アプリではなく手書きメモアプリだが、凝った絵を描くことはないので十分だった。こんな図だ。

こんなのでも、普通にパソコンでマウスを使って描いていたら、一枚あたりそこそこ時間がかかってしまう。しかし、手書きならあっという間だ。ざっと描いて選択し、クリップボードにコピーする。すると、この画像はメイン環境のMacbookで実行しているJuputer Notebookのマークダウンセルにペーストできてしまう。あっというまに図入りのMarkdownが完成だ。画像の作成・取込み作業としては、ほぼ最小手数なのではないだろうか。

このぐらいの手間で済むなら、図なんかなんぼでも描けてしまう。絵の汚さに我慢できればの話だが。調子に乗って、汚い字で描きまくってしまった。編集部の皆様の負担になったのではないかと思うと、大変申し訳無い次第だ…

問題点

しかし好事魔多し。そう都合の良いことばかりは起きないもので、ちょっとした問題点にもぶつかった。

一つは、Markdownのセル一つには、画像を一つだけしかペーストできない、という点だ。操作上はいくつでも画像を張り込めるのだが、内部的には最後にペーストした一つだけしか保存されていない。まあ、セルを分ければ良いのだが、あまりこういう使い方はしたことがなかったので知らなかった。

もう一点はJupyter NotebookというよりはJupyter NotebookをSphinxに取り込んで文書化するnbsphinxの問題だと思うが、Notebookに別々のセルであっても同じ名前の画像ファイルがあると、うまく画像を表示できない。Jupyter Notebookに画像をペーストすると、すべてimage.png という名前で保存されてしまうので、結局画像は一つしか使えない、ということになってしまう。

入稿もJupyter Notebookで可能、という点は確認済みだったのでPDF化は必須ではないが、原稿のチェックをするときにはPDFは便利だ。できればSphinxを使いたい。

このため、別途簡単なスクリプトを作成し、ipynbファイルを読み込んで、画像ファイルの名前とMarkdownのマークアップを修正してからビルドするようにする必要があった。

書き上げてみて

Jupyter Notebook + iPadでの原稿執筆はなかなか快適で、気がついたら予定のページ数を大きく超過してしまい、後の削除が大変だった。一年ぐらい寝かしたら、削除部分も復活して完全版をどっかに公開するかもしれない。

しかし、Jupyter Notebookは、最初の執筆はあまり問題ないが、仕上げの推敲がめんどうだ。しょせんブラウザ上のエディタなので高度な編集機能は使えないし、テキストがセル単位に細かく分割しているため、広い範囲の修正には不便だ。また、文章の順番の入れ替えなどもエディタほど簡単ではない。

今回は30ページほどの記事なので大したことはなかったが、これが100ページ200ページとなると、なにか対策が必要となるかもしれない。

その他の問題

Jupyter Notebookとは今回の記事ではテキストのエンコーディングも解説していて、その中でいわゆるシステム固有文字の㈱や①をどうしても使いたかった。

しかし、デフォルトのSphinxではpLaTeXという、システム固有文字をサポートしていないツールが使われている。LaTeXで丸付き文字を出力することは可能なので、この機能をSphinxから利用できないか相談してみたところ、なんとSphinxメンテナの小宮氏から、upLaTeXというユニコードをサポートしているLaTexで出力する方法を教わり、事なきを得た。Sphinxの conf.py に次の設定を加えることで、upLaTeXが使われるようになる。

language = 'ja'
latex_elements = {
    'classoptions': ',uplatex,dvipdfmx',
}

小宮氏には厚くお礼申し上げる次第である。