18
16

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

nbsphinx の紹介

Last updated at Posted at 2017-12-06

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.htmlExample of configuration file に 下記の1行だけを追加したもの)

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

    Tutorials
    ---------
    
    .. toctree::
       :glob:
    
       notebooks/*
    
    
  5. readthedocshttps://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 の紹介でした。

18
16
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
18
16

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?