Heading ranking not respected when using ipynb source

[tiagopereira]

When using nbsphinx with jupyter notebooks, the output does not respect the heading rankings (e.g. #, ##, ###) if they are entered in separate cells. If all content is entered on a single notebook cell, it works as expected. But if a cell has only a lower-level heading (e.g. ###), this is "promoted" to main header (#).

In the images below I used the first two notebooks from nbsphinx documentation. The index.rst file contains the following:

.. toctree::
   :maxdepth: 3
   :glob:

   installation.ipynb
   usage.ipynb

Using the RTD theme, one can see that all lower headings in cells get promoted to main heading and appear on the navigation bar on the left:

(This is not limited to the RTD theme.)

I am using MacOS, with the packages from Anaconda:

docutils                  0.13.1                   py36_0
nbformat                  4.3.0              py36_intel_0  [intel]  intel
nbsphinx                  0.3.1                      py_0    conda-forge
sphinx                    1.6.6                    py36_0
sphinx_rtd_theme          0.2.4                    py36_0
traitlets                 4.3.2              py36_intel_1  [intel]  intel

[mgeier]

What version of pandoc are you using?

[tiagopereira]

$ pandoc --version
pandoc 1.15.0.6
Compiled with texmath 0.8.2.2, highlighting-kate 0.6.

[rddaz2013]

#153 and https://github.com/sphinx-doc/sphinx/commit/6654687ec19a446388b7799c1e11b361921c4f7b

 # Same as util.nested_parse_with_titles but try to handle nested
 # sections which should be raised higher up the doctree.

[tiagopereira]

Updating pandoc seems to fix the problem. Now using 1.19.2.1 and it works fine. Maybe some minimum pandoc version should be listed in the requirements?

[mgeier]

@tiagopereira Good to know that it works with a newer version.

I don't know the exact versions where it works and where it doesn't. Do you?

Any ideas how we could document this in a reasonable way?

Feel free to make a PR with documentation updates!