【エラー対応付き】Markdown記法とTable of Contentsアドオン(Nbextensions)導入方法【Jupyter Notebook】

【エラー対応付き】Markdown記法とTable of Contentsアドオン(Nbextensions)導入方法【Jupyter Notebook】

いまだ教本の第四章:Numpyの写経を行っているところです。42ページもあるし、1回じゃ頭に入らないんですよね。。。

で、Jupyter Notebookをはじめて使う人の気持ちになったとき、Markdown記法Table of Contents(目次)アドオン群(Nbextensions)の導入について、書いておいた方がいいなと思ったので、記事にしたいと思います。

nojo

このサイトでは、 教本:Pythonによるあたらしいデータ分析の教科書 に沿った方法で、環境を作成しています。

Python関連の試験合格を目指している方や、Jupyter NotebookではじめてMarkdownを書く方等のお役に立てれば幸いです。

目次

やりたいことのイメージ

Jupyter Notebookでコードを書いていると、いくらコメントアウトしても一見で何を書いているのか分かりにくくなりませんか?とくに開発プロジェクトメンバに共有する事案では、一見で分かりやすいドキュメントが求められます。自分に対してもあとで見直したとき、分かりやすいドキュメントの方がいいですよね。

Jupyter NotebookはMarkdownでドキュメントが書ける仕様になっています。これを使って見出しや強調、インデント等で文章に様々な装飾を行いましょう。

Markdownとは:文章を構造化しながら記述するための記法のひとつで、HTML(マークアップ)の軽量版です。ちょっとお作法は違うけど類似のものにTexstile記法があります。両者ともタグを書かないのにHTML形式で表示してくれるので、超便利です。

その上で、下図・左側でいうところの「Contents」に目次を表示してくれるTable of Contentsというアドオンを設定していきます。そのためにはNbextensionsというアドオン群のインストールが必要なので、その方法もくわしく解説していきたいと思います。

JupyterNotebook_Markdownと目次
JupyterNotebook_Markdownと目次

これからやる工程をまとめると、

  1. PowerShellで仮想環境のJupyterNotebookを起動
  2. 簡単なMarkdownを書いてみる
  3. Nbextensionsのインストール
  4. Table of Contentsの有効化
  5. 目次の見え方確認

になります。Nbextensionsあたりが混乱ポイントかなと思うので、その部分を重点的に解説していきます。

前準備

Power Shellの使い方や仮想環境の入り方、JupyterNotebookの起動方法については省略します。以下の記事にすべて記載していますので、ご参照ください。

※Jupyter Notebookのファイルを開いて、次にお進みください。

Markdown記法での書き方

STEP
セル挿入

見出しをつけたいと思っているひとつ上のセルを選択 >【+】(insert cell bellow)をクリックします。

JupyterNotebook_セル挿入
JupyterNotebook_セル挿入

STEP
セルをMarkdown化

セルが挿入されます(右側、水色枠の部分)。

通常は「Code」になっているプルダウンから「Markdown」を選択します。

JupyterNotebook_セルをMarkdown化
JupyterNotebook_セルをMarkdown化

STEP
Markdownを入力

この例では、見出しとリストを作成します。

JupyterNotebook_Markdown挿入
JupyterNotebook_Markdown挿入

いろんな書き方があるんですが、まずは動作確認をしてもらうのが一番なので、下記をそっくりそのままコピペRun実行してみて下さい。

※Runのおさらい:Runボタン実行 or [Shift]+[Enter]

## 配列作成、タイプ/要素数確認
- array
- type
- shape

STEP
Markdownの表示確認

Run実行結果をみてみましょう。冒頭の数字表記(1や1.1)はない状態で、「##」が見出し「-」がリストになっていると思います。

JupyterNotebook_Markdown表示
JupyterNotebook_Markdown表示

このような形でいくつか見出しとリストをMarkdownで挿入してみて下さい。

Markdown記法をもっと学びたい方は、先輩方が詳しいページをたくさん作っていらっしゃるので、それを参考にされると良いかと思います。以下、ワタシが参考にしているページを貼っておきます。

Nbextensionsの導入(エラー対応付き)

お次はNbextensionsというJupyter Notebookの拡張機能(アドオン)を導入していきます。このNbextensionsは後述するTable of Contents(目次表示機能)を含んだアドオンの親玉みたいなもんです。コマンド叩いてちゃちゃっと導入しちゃいましょう。

天使ちゃん

ちゃっちゃ、ちゃっちゃ!

nojo

サンドの某有名コントを思い出すね。

STEP
pipでNbextensionsをインストール
pip install jupyter_contrib_nbextensions

はい、「はじまりはいつもpip….」でインストールです。Power Shell(以降、省略)に上記コマンドをコピペして実行して下さい。

STEP
Nbextensions設定表示ファイルをインストール
jupyter contrib nbextension install --user

こんどは「はじまりはいつもpip…..」ではなく、「jupyterからはじまる」コマンドになります。

STEP
Nbextensions構成管理ライブラリをインストール
pip install jupyter_nbextensions_configurator

はい、また帰ってきました「はじまりはいつもpip….」でnbextensions_configuratorをインストールします。ここからはその方の環境によりますが、ワタシの場合は、

ERROR: Could not find a version that satisfies the requirement jupyter_nbxtensions_configurator(From versions: none)

ERROR: No matching distribution found for jupyter_nbxtensions_configurator

が表示されました。

pipバージョンとマッチしたjupyter_nbextensions_configuratorがないエラー
pipバージョンとマッチしたjupyter_nbextensions_configuratorがないよエラー
nojo

WARININGメッセージを読む限り、pipを最新の22.0.2にアップグレードすれば何とかしてくれそうですね。

pipを最新のバージョンにあげましょう。

python -m pip install -U pip

pipのバージョンアップが終わったら、[↑]キーを何度か押すコマンドの履歴を表示>「pip install jupyter_nbextensions_configurator」を再度実行して下さい。ワタシの場合はこれを2回実行してインストールできましたので、エラー表示されてもひるまずに何度か実行してみて下さい。

STEP
Nbextensions構成管理ライブラリを有効化
jupyter nbextensions_configurator enable --user

最後に上記コマンドを実行して、nbextensions_configuratorを有効化して下さい。

Table of Contentsの有効化と設定

ここまでの作業で、Jupyter Notebookにnbextensions_configuratorが追加されていますので、それを使ってTable of Contentsを有効化していきます。ついでに個人のお好みですが設定も少し紹介していきます。

STEP
「Edit」>「nbextentions config」をクリック

sdfsdfsdfsdf

JupyterNotebook:Edit > nbextentions config
JupyterNotebook:Edit > nbextentions config
STEP
Table of Contentsの有効化

新しいタブで下記の画面が表示されます。

まず、disable configuration for nbextensions without explicit compatibillity………のチェックOFF > Table of Contents(2)にチェックONして下さい。

Configurable nbextensions
Configurable nbextensions
STEP
マークアップの設定とイメージ

少し下にスクロールダウンすると、目次セクションのマークアップ色の設定画面があります。ガッツリ英語ですので、分かる方は設定してみて下さい。もう少しスクロールダウンすると、イメージしやすいアニメーションが再生されていますので、一度見てみられることをおススメします。

Nbextensions configuration
Nbextensions configuration

設定が完了したら、タブを閉じて下さい。

Table of Contentsの表示

ここまで来ても、まだ目次は表示されません。JupyterNotebookに目次アイコン(下図赤枠)が表示されているので、それをクリックすることで目次が表示されます。

JupyterNotebook_Table of Contentsアイコン
JupyterNotebook_Table of Contentsアイコン

はい、目次が表示されました。デフォルトでは見出しに対し、自動的にナンバリングする設定になっています。それをやめたい場合は、赤枠で示している歯車アイコンをクリックします。

JupyterNotebook:Table of Contents > 設定(歯車)アイコン
JupyterNotebook:Table of Contents > 設定(歯車)アイコン

Automatically number headingsチェックOFFで、番号表示がなくなったことが分かると思います。この辺はお好みに応じて設定して下さい。

JupyterNotebook:Table of Contents > 設定画面
JupyterNotebook:Table of Contents > 設定画面

以上、Markdown記法とTable of Contentsアドオン導入方法(エラー対応付き)でした。みなさんもMarkdownを利用して、一見で分かりやすいドキュメントを作ってみてください。ワタシはもう少しNumpyの理解を深めたいと思います。

最後まで読んで下さり、ありがとうございました

よかったらシェアしてね!
目次
TOP
目次
閉じる