Read the Docs > Jupyter Notebookドキュメントを公開しようとした > ビルド > Extension error: Could not import extension nbsphinx (exception: No module named nbsphinx)


動作環境
GeForce GTX 1070 (8GB)
ASRock Z170M Pro4S [Intel Z170chipset]
Ubuntu 16.04 LTS desktop amd64
TensorFlow v1.2.1
cuDNN v5.1 for Linux
CUDA v8.0
Python 3.5.2
IPython 6.0.0 -- An enhanced Interactive Python.
gcc (Ubuntu 5.4.0-6ubuntu1~16.04.4) 5.4.0 20160609
GNU bash, version 4.3.48(1)-release (x86_64-pc-linux-gnu)
scipy v0.19.1
geopandas v0.3.0
MATLAB R2017b (Home Edition)
ADDA v.1.3b6
gnustep-gui-runtime v0.24.0-3.1
sphinx-build 1.7.1

関連: Read the Docs > 入門してみた > sphinx-quickstart生成テンプレートの公開まで | PDF版のドキュメント取得

概要

SphinxではJupyter Notebookドキュメントを扱えるらしい。

参考: Sphinxを便利にして、みんなに使ってもらいたい

Jupyterのノートブックを取り込む(2017-02-06追加)

ipynbファイルが扱えるのであれば、rst記法は必要最低限でいいかもしれない、という安易な考えを持つ今日このごろ。

使ってみた

$ sudo pip install nbsphinx

Jupyter / matplotlib > 2Dの数値を画像化
に記載のmake_plot_2d.pyを実装し、実行。

$ python make_plot_2d.py > 2d.csv

Jupyter Notebookを起動しshow2dimage_180310.ipynbという名前でこちらのJupyterコードを作成。

index.rstのtoctreeを以下のようにする。

index.rst
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   show2dimage_180310

_build/html/index.htmlを生成してみる。

$ make html
Running Sphinx v1.7.1
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 3 source files that are out of date
updating environment: 3 added, 0 changed, 0 removed
reading sources... [100%] show2dimage_180310                                    
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/yasokada/ReadTheDocs_180310/docs/.ipynb_checkpoints/show2dimage_180310-checkpoint.ipynb: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] show2dimage_180310                                     
/home/yasokada/ReadTheDocs_180310/docs/index.rst:9: WARNING: toctree contains reference to document 'show2dimage_180310' that doesn't have a title: no link will be generated
generating indices... genindex
writing additional pages... search
copying images... [100%] _build/doctrees/nbsphinx/show2dimage_180310_0_0.png    
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 2 warnings.

The HTML pages are in _build/html.

警告が出ているが、今回は保留とする。

生成ページの確認

Google Chromeで生成ページの確認をする。

$ google-chrome _build/html/index.html 

開いたページの左メニューに下記が見つかるので<no title>をクリックする。

Next topics
<no title>

Jupyter Notebookのページが開く。ローカル環境では問題はない。

Read the Docsでのビルド

下記をGitHubリポジトリに追加した。

  • 2d.csv
  • show2dimage_180310.ipynb
  • conf.py
  • index.rst
  • make_plot_2d.py
    • RTDには無関係だが、GitHub管理するため

Read the Docs上にてビルドしてみた。
Build failedになる。

対処

2018年3月10日現在、Read the Docs上ではJupyter Notebookファイルは表示できないのかもしれない。

GitHubページではJupyter Notebookのレンダリング機能はあるので、そちらにリンクだけする、というのがとりあえずの対処となるだろう。

下記においてLinkという項目とshow2dimage_180310のリンクを追加した。

index.rst
.. ReadTheDocs_180310 documentation master file, created by
   sphinx-quickstart on Sat Mar 10 08:22:18 2018.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to ReadTheDocs_180310's documentation!
==============================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:


Link
====

`show2dimage_180310 <https://github.com/yasokada/ReadTheDocs_180310/blob/master/docs/show2dimage_180310.ipynb>`_


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

以下のようなページとなる。
http://readthedocs-180310.readthedocs.io/en/latest/#

PDF版ドキュメントにはLinkの項目は見つからない点は未消化。