nbsphinx の紹介

nbsphinx とは

nbsphinx は Jupyter Notebook を Sphinx のドキュメントソースとして扱うための Sphinx拡張パッケージです。
ipynb ファイルを一度 reStructuredText に nbconvert してから Sphinx のビルドを実行されていた方もいらっしゃるのではないでしょうか。
nbsphinx を導入すると convert の必要が無くなり、ダイレクトに ipynb ファイルを Sphinx でビルドできるようになります。

nbsphinx 活用の実例

nbsphinx の活用の実例として

• ipynb ファイルしか持たない既存の github repository を
• nbshinx を用いて nbconvert をかませることなく Sphinx でビルドし
• その成果物を readthedocs で公開する

ことを行う repository
https://github.com/kozo2/biopython-notebook/tree/nbsphinx
を示します。

この repository (のnbsphinx branch) で行ったことは下記の5ステップだけです。
これだけで http://biopython-tutorial.readthedocs.io/en/latest/ のように Jupyter Notebook が Sphinx でビルドされたサイトを公開できます。

1. https://github.com/tiagoantao/biopython-notebook (biopythonというバイオインフォマティクスのためのPythonパッケージのチュートリアルnotebook集) を fork

2. 下記の1行だけを書いた requirements.txt を追加

   nbsphinx
   

3. conf.py を追加 (その内容は http://www.sphinx-doc.org/en/stable/config.html の Example of configuration file に 下記の1行だけを追加したもの)

   extensions.append('nbsphinx')
   

4. 下記だけを書いた index.rst を追加 (notebooks directory 下には複数の ipynb ファイルがあります)

   Tutorials
   ---------
   
   .. toctree::
      :glob:
   
      notebooks/*
   
   

5. readthedocs で https://github.com/kozo2/biopython-notebook/tree/nbsphinx をビルドするように設定

nbsphinx で得られるメリットとまとめ

Jupyter Notebook は GitHub がサボートしているので Sphinx でのビルド (とreadthedocsでの公開) にあまり興味を持たれないかもしれません。
ですが私は下記のようなメリットがあると思います。

1. アウトラインが把握しやすくなる。各ヘッダーへのジャンプが可能になる。
2. スマートフォン，タブレット端末での閲覧に適した見栄えが得られる。
3. 実行するのではなく，見たいだけの場合は静的なドキュメントサイトを見たくなる (気がする)。
4. 美しく整形された pdf や epub での export。
5. 1.2.3.4. に伴うさらなる Notebook 推敲のモチベーション喚起。

上記には特に興味が無くても
nbsphinx はとにかく便利と思うので是非試してその手軽さを体感していただきたいです。

以上 nbsphinx の紹介でした。