MkDocsでJupyter Notebookを使えるようにする

MkDocs関連のpythonパッケージmkdocs-jupyterを使うわけですが、MkDocsでJupyter Notebookを使えるようにする方法を紹介します。

インストール

pip installする。ついでにrequirements.txtを書き換えておく。

python -m pip install mkdocs-jupyter
python -m pip freeze > requirements.txt

設定

mkdocs.ymlに以下を追加。 mkdocs serveしていて、"mkdocs-jupyterがないよ"というエラーがでたら、再起動してください。

plugins:
    - mkdocs-jupyter

jupyter環境を整える

MkDocsでドキュメントを書きつつ、Jupyterで分析のノートブック作っていくことになる。

• MkDocs用 : MkDocsをビルドしたり、mkdocs serveしたりする環境
• Jupyter用 : Jupyterで分析する環境

MkDocs環境が汚れるのは嫌なので、２つの環境を作って別々でパッケージ管理していくのがおすすめ。

MkDocs用

これまでMkDocsをビルドする環境を.venvで管理していたので、違う名前で作り直す。 事前のdeactivateも忘れずに。

まずは、今は言っているMkDocs用のパッケージリストをバックアップして削除。

python -m pip freeze > requirements.txt
deactivate
rm -rf .venv

.venv-mkdocsという名前で仮想環境を作り直す。

python -m venv .venv-mkdocs
source .venv-mkdocs/bin/activate
python -m pip install -r requirements.txt

これで復活。簡単ですね。

.gitignoreに、リネームした.venv-mkdocsも無視するように追加しておく。

.venv
.venv-mkdocs

MkDocsはOSのターミナルで今後ビルドなり、mkdocs serveする。

mkdocs serve

これで現状復帰。

Jupyter用

あとは、よく使われる.venvをJupyter用に作る。

mkdocs serveしているMkdocs用とは別のターミナルで作業する。

python -m venv .venv
source .venv/bin/activate
python -m pip install jupyterlab

サンプルノートの作成

Jupyter labを立ち上げるが、

• Jupyter用のターミナル
• 範囲を絞るためにこの文書のあるディレクトリ

で起動する。

jupyter lab docs/site

mkdocs-jupyter-sample.ipynbというノートブック作成。 このファイル。

あとはmkdocs.ymlのnavにリンクを追加。

nav:
  - Home: index.md
  - Junk Note:
      - サイト運営:
          - サイト運営: site/index.md
          - MkDocsでJupyter: site/mkdocs-jupyter.md
          - jupyterサンプル: site/mkdocs-jupyter-sample.ipynb