Hide prompt numbering and display headings at right size

[cdeepakroy]

Background
I am an R&D engineer at a company called Kitware and I am currently involved in developing an open-source API for the analysis of histopathology analysis that uses ReadTheDocs for providing documentation. We are currently exploring the use of ipython notebooks to create examples for the functionality in our API. After a bit of googling, i found nbsphinx to be a great tool to show ipython notebooks in ReadTheDocs. Once i get a prototype working well, i want to pitch the use of nbsphinx with the rest of the team in our project and also the rest of our company

Issue
Here is rendering of an ipython notebook on ReadTheDocs using nbsphinx. I am currently facing two issues:

• I want to remove the prompt numbering such as In [1], In [2] etc. How do i do this? Is there a metadata field i can set at the notebook level to hide these?
• The section headings are not being rendered at the correct size on ReadTheDocs. However, they render fine on github. Here is my docs/conf.py. Is there a property i need to set here to fix this?

[cdeepakroy]

The dispay of markdown seems to be delegated to markdown2rst which seems to use pandoc. Wondering if the incorrect display of headings is related to the installation of pandoc. Does ReadTheDocs have the correct version of pandoc installed? How could i check this?

[mgeier]

The behavior of the header levels is a feature of docutils (on which Sphinx is based), see: #22 (comment). I don't think I can do anything to change that.

If you use consistent heading levels, you won't have this problem. You only have it because you are mis-using a header to make some words larger and fatter. AFAIK there is no way to make text larger in Markdown (without using inline HTML). You can use bold and _bold italics_, though.

Regarding prompt numbers: Why would you want to get rid of them?

Currently, there is no way to do that, but it would be certainly possible to implement that feature.

[mgeier]

See also jupyter/nbconvert#40.

[cdeepakroy]

Thanks for the reply.

I feel the capability to choose the heading size in a what-you-see-is-what-you-get fashion is necessary. I am trying to use # something for the notebook title and #### something for all subsection titles. After reading the comment #22 you mentioned, it seems to force me to come up with some dummy ## and ### headers in between when i do not want them is weird. Where should i post this as an issue? docutils/sphinx?

I feel the purpose of the prompt numbers is probably to cache outputs to be used later. In anycase, for the purpose of creating examples of API usage with ipython notebooks and rendering them in ReadTheDocs using nbsphinx, the display of prompt numbers looks annoying. I would instead prefer a rendering like this from an old version of nbsphinx.

[mgeier]

If you think about what headings really mean semantically, it doesn't make sense to skip a heading level. If you think in section numbers, after section 3 you wouldn't continue with section 3.0.0.1 but with section 3.1, right?

If a given heading level is shown in a too large font for your taste, you may be able to make it smaller with some additional CSS.

You can try to open an issue at either docutils or sphinx, but I don't think you'll get very far either way. The way how nested sections are handled is in the very core of docutils's internal representation. AFAIK, there are no explicit heading levels, only the amount of nesting specifies the resulting heading level. Once #36 is realized, there will probably be some way to manipulate the internal representation, but I don't know if it's possible to insert "invisible" nested sections (the levels ## and ### in your case).

I like the prompts because they keep some resemblance with the original notebook. I don't want to hide that there is a notebook behind the scenes. On the contrary, often I fear that this is not visible enough!
Also, the prompts are helpful to discern between output streams and "normal" output.
If you don't like the look of the notebook cells, you should have a look at http://sphinx-gallery.readthedocs.io/, probably that's a better fit for your needs?

If you have some CSS changes that make nbsphinx's appearance nicer (see also #11), feel free to send a PR!

[mgeier]

BTW, in some themes you can make the prompts dissapear by injecting some CSS:

.nbinput > :first-child,
.nboutput > :first-child {
    min-width: 0 !important;
}

[mgeier]

You can also try #54 and use this in your conf.py:

nbsphinx_prompt_width = 0

[mgeier]

@cdeepakroy Any news?

[cdeepakroy]

@mgeier We just decided to switch to sphinx-gallery. With jupyter notebooks doing code review of changes in the notebook over a github PR is clumsy. So sphinx-gallery seems better for us in that sense.

[mgeier]

Thanks for the update, sounds reasonable. I'm closing this ...

[mgeier]

Currently (nbsphinx version 0.9.1), the recommended way to remove the prompts in HTML output is via CSS:

.nbinput .prompt,
.nboutput .prompt {
    display: none;
}

See https://nbsphinx.readthedocs.io/en/0.9.1/custom-css.html#For-a-Single-Notebook