Update nbsphinx to Recognize text/x-rst Mimetype for Raw Cells

[MacHu-GWU]

With the release of [nbconvert version 7.16.5](https://github.com/jupyter/nbconvert/blob/main/CHANGELOG.md#7165 according to nbconvert) on 2025-01-02, the mimetype for reStructuredText raw cells has been updated from text/restructuredtext to text/x-rst . This change affects nbsphinx’s ability to detect titles in notebooks where the first cell is a raw reStructuredText cell. 

Current Behavior:

When the first cell of a notebook is a raw reStructuredText cell with the mimetype text/x-rst, nbsphinx does not recognize the document’s title, leading to warnings such as:

WARNING: toctree contains reference to document 'path/to/notebook' that doesn't have a title: no link will be generated

Proposed Solution:

Modify nbsphinx to recognize both text/restructuredtext and text/x-rst mimetypes when processing raw cells. Specifically, update the condition in the nbsphinx source code to:

{%- elif raw_mimetype in ['text/restructuredtext', 'text/x-rst'] %}

This change will ensure compatibility with notebooks using either mimetype.

This issue will be fixed by PR #834

[MacHu-GWU]

Hi @mgeier, do you think this make sense?

[MarkusZimmerDLR]

I was just about to open an issue, since I am not able to get raw cells with reStructuredText working.

The cell in the notebook looks like this.

    {
      "metadata": {
        "raw_mimetype": "text/restructuredtext"
      },
      "cell_type": "raw",
      "source": "sanity check",
      "id": "900367db7c93429e"
    },

I also tried the text/x-rst mimetype, without success. The compiled documentation features the content of the notebook correctly. The mentioned cell above (all with raw type in combination with reST), however, is not rendered. If I download the ipynb, it is still there.

I tried this with various themes and python versions (thus, different package versions) - the outcome is the same.

Environment 1 (newer):

docutils                  0.21.2             pyhd8ed1ab_1    conda-forge
jinja2                    3.1.6              pyhd8ed1ab_0    conda-forge
jupyter_client            8.6.3              pyhd8ed1ab_1    conda-forge
jupyter_core              5.7.2              pyh31011fe_1    conda-forge
jupyterlab_pygments       0.3.0              pyhd8ed1ab_2    conda-forge
nbclient                  0.10.2             pyhd8ed1ab_0    conda-forge
nbconvert                 7.16.6               hb482800_0    conda-forge
nbconvert-core            7.16.6             pyh29332c3_0    conda-forge
nbconvert-pandoc          7.16.6               hed9df3c_0    conda-forge
nbformat                  5.10.4             pyhd8ed1ab_1    conda-forge
nbsphinx                  0.9.7              pyhd8ed1ab_0    conda-forge
pandoc                    3.7.0.1              ha770c72_0    conda-forge
pandocfilters             1.5.0              pyhd8ed1ab_0    conda-forge
pydata-sphinx-theme       0.16.1                   pypi_0    pypi
python                    3.13.3          hf636f53_101_cp313    conda-forge
sphinx                    8.2.3              pyhd8ed1ab_0    conda-forge
sphinx-autoapi            3.6.0                    pypi_0    pypi
sphinxcontrib-applehelp   2.0.0              pyhd8ed1ab_1    conda-forge
sphinxcontrib-devhelp     2.0.0              pyhd8ed1ab_1    conda-forge
sphinxcontrib-htmlhelp    2.1.0              pyhd8ed1ab_1    conda-forge
sphinxcontrib-jsmath      1.0.1              pyhd8ed1ab_1    conda-forge
sphinxcontrib-qthelp      2.0.0              pyhd8ed1ab_1    conda-forge
sphinxcontrib-serializinghtml 1.1.10             pyhd8ed1ab_1    conda-forge

Environment 2 (older):

docutils                  0.21.2                   pypi_0    pypi
ipython                   9.0.2              pyhfb0248b_0    conda-forge
jinja2                    3.1.6                    pypi_0    pypi
jupyter-client            8.6.3                    pypi_0    pypi
jupyter-core              5.7.2                    pypi_0    pypi
jupyter-events            0.12.0                   pypi_0    pypi
jupyterlab                4.4.2                    pypi_0    pypi
jupyterlab-pygments       0.3.0                    pypi_0    pypi
jupyterlab-server         2.27.3                   pypi_0    pypi
jupyter-lsp               2.2.5                    pypi_0    pypi
jupyter-server            2.16.0                   pypi_0    pypi
jupyter-server-terminals  0.5.3                    pypi_0    pypi
nbclient                  0.10.2                   pypi_0    pypi
nbconvert                 7.16.6                   pypi_0    pypi
nbformat                  5.10.4                   pypi_0    pypi
nbmake                    1.5.5                    pypi_0    pypi
nbsphinx                  0.9.7                    pypi_0    pypi
pandoc                    3.6.4                ha770c72_0    conda-forge
pandocfilters             1.5.1                    pypi_0    pypi
python                    3.12.9          h9e4cc4f_1_cpython    conda-forge
sphinx                    8.1.3                    pypi_0    pypi
sphinx-autoapi            3.6.0                    pypi_0    pypi
sphinx-book-theme         1.1.4                    pypi_0    pypi
sphinxcontrib-applehelp   2.0.0                    pypi_0    pypi
sphinxcontrib-devhelp     2.0.0                    pypi_0    pypi
sphinxcontrib-htmlhelp    2.1.0                    pypi_0    pypi
sphinxcontrib-jsmath      1.0.1                    pypi_0    pypi
sphinxcontrib-qthelp      2.0.0                    pypi_0    pypi
sphinxcontrib-serializinghtml 2.0.0                    pypi_0    pypi

Any idea?

[MarkusZimmerDLR]

your sphinx <...> != 8.2.0, != 8.2.1', does not do anything by the way if sphinx 0.8.3 exists.

at least no with respect to your statement in the latest release

Disable Sphinx 8.2+ (for now)

[MarkusZimmerDLR]

Downgrading sphinx < 8.2 for a new environment does not resolve the Issues.

Additionally, setting nbsphinx < 0.9 results in an error

Extension error (nbsphinx):
Handler <function html_collect_pages at 0x7f6f58728a40> for event 'html-collect-pages' threw an exception (exception: module 'sphinx.util' has no attribute 'status_iterator')
make: *** [Makefile:66: html] Error 2

Seems like a dependency issue to me.

[MarkusZimmerDLR]

I am an idiot and I am sorry.

For the time being, replacing all the text/x-rst with text/restructuredtext mimetypes works.

[mgeier]

This has been fixed in #834.