PIB

Sphinx の .rst で python3 の code-block に Jupyter Notebook のコードを貼ると先頭が ! 行で shell を呼んでる部分がお気に召さないらしく、リテラルブロックがが python3 として解釈できないと言われる。

Bing 先生に聞いてみたところ、python3 ではなく ipython3 の code-block にすればよいらしい。

Q:

sphinx の code-block に jupyternotebook の shell command の呼び出しを書くと、リテラルブロックが python3 として解釈できないと言われる。
例えば、
```
.. code-block:: python3

   !curl
```
のようなことを書くと、! がお気に召さないらしい。
これはどうしたらよい？

A:

こんにちは、これはBingです。😊

sphinx の code-block に jupyternotebook の shell command の呼び出しを書くと、リテラルブロックが python3 として解釈できないと言われる問題について、いくつかの解決策があります。

一つは、code-block の言語を console にすることです1。これはインタラクティブなセッションに適しています。例えば、

.. code-block:: console

   $ curl
Copy
もう一つは、code-block の言語を bash や sh にすることです2。これはシェルスクリプトに適しています。例えば、

.. code-block:: bash

   $ ls -lsa .
   $ make file
Copy
ハイライトが正しく機能しない場合があるかもしれませんが、少なくとも可能性を与えます。また、ファイルの先頭でデフォルトのハイライトを設定することもできます2。

.. highlight:: sh
Copy
これらの方法で問題が解決するかどうかお試しください。

Q:

そうじゃなくて、sphinx の code-block に jupyternotebook の code cell の内容を入れたいんだけど、code-block の種類として jupyternotebook とかは無理なの？

A:

sphinx の code-block に jupyternotebook の code cell の内容を入れたいということですね。その場合、code-block の種類として jupyternotebook は無理ではないですが、いくつかの手順が必要です。

まず、jupyternotebook のファイルを sphinx のプロジェクトに含めるために、nbsphinx や MyST-NB という拡張機能のどちらかを使う必要があります。これらの拡張機能は、.ipynb ファイルや jupytext がサポートする他のフォーマットのファイルを sphinx のソースファイルとして読み込むことができます。

次に、jupyternotebook の code cell に含まれるインタラクティブなウィジェットを HTML に埋め込むためには、HTML ドキュメントを生成する前にウィジェットの状態を保存する必要があります。そうしないと、ウィジェットは空っぽになってしまいます。エディターによって保存方法は異なりますが、一般的にはメニューから選択するか、自動的に保存する設定を有効にするかのどちらかです。

最後に、code-block の言語として ipython3 を指定することで、jupyternotebook の code cell を sphinx のドキュメントに表示できます。例えば、

.. code-block:: ipython3

   In [1]: import numpy as np

   In [2]: x = np.arange(10)

   In [3]: x.mean()
   Out[3]: 4.5
Copy
これらの方法で jupyternotebook の code cell を sphinx の code-block に入れることができるはずです。