Add option to hide cell input of a single cell using its metadata.

[BenZickel]

Resolves #15.

Removing a cell's input from the HTML/LaTeX output is done by adding the below to the cell metadata:

"nbsphinx": "hidden-input"

If you'd like to remove the entire cell from the HTML/LaTeX output you can use an already existing feature which accomplishes this by adding the below to the cell metadata:

"nbsphinx": "hidden"

[mgeier]

Thanks for this PR!

Can you please address the comments I made in #15?

[BenZickel]

I've reviewd #15 and some of its references and I think that this PR is the least disruptive from all other propositions, as it utilizes the existing metadata keyword nbsphinx which is already in use.

My specific use case is for creating documentation using nbsphinx in which there are input cells which are not informative and confuse the reader. For example when generating diagrams, the reader is not interested in the code used to geenrate the diagram. This use case was also mentioned in #185 (comment).

If there are any other comments I'll make additional changes as required, and thanks for creating nbsphinx!

[mgeier]

... there are input cells which are not informative and confuse the reader. For example when generating diagrams, the reader is not interested in the code used to geenrate the diagram.

Are you sure? I'm often very much interested in how a good-looking diagram was generated.

I agree that putting a whole blob of unstructured plotting code into a huge code cell is likely distracting to readers. I recommend moving most of the auxiliary code into functions in a separate .py file (or multiple) which you can then import in a code cell.

I'm doing this all the time, here's a random example: https://splines.readthedocs.io/en/0.3.2/euclidean/catmull-rom-non-uniform.html#Animation

This way you are not hiding how to generate the diagram (and make it easier for a reader to understand), but you are still avoiding (most of) the noise.

If there are any other comments I'll make additional changes as required

Yes, there are many comments in #15, I don't want to copy all of them here, but for starters, here is one (from #15 (comment)):

I thought about implementing this in nbsphinx, but I wanted to wait until it's supported in the Jupyter live notebook and in nbconvert, because I wanted to re-use whatever notebook/cell metadata they are using.

Or what about this one (from #15 (comment)):

I think the most reasonable course of action is to limit this feature to HTML output and implement a "toggle" button similar to the one used in https://jupyter.org/jupyter-book/features/hiding.

Admittedly, the link is broken, let me know if you don't find what I meant at that time.

[BenZickel]

Thanks for the review @mgeier!

I also like to know how good looking diagrams are generated. If you are creating them using dedicated .py files, that you don't mind users reading them, you would need to point to the source code of the notebook and dedicated .py files anyhow, in which case all cells are shown, including hidden and removed ones.

Would using a different tag for hiding (or should I say removing) an input cell be sufficient (see for example https://jupyterbook.org/en/stable/interactive/hiding.html#removing-code-cell-content)?

[mgeier]

If you are creating them using dedicated .py files, that you don't mind users reading them, ...

On the contrary, I definitely want users to be able to read them.

... you would need to point to the source code of the notebook and dedicated .py files anyhow, ...

Yes, and I consider this good practice.

... in which case all cells are shown, including hidden and removed ones.

That's true, but I'd like to make it as easy as possible for readers. Having to open and sift through the source notebook is just an additional obstacle that I would like to avoid.

Also, if there is no hint in the HTML-rendered version (because the input cell was hidden), readers might not know that there's even something hidden from them they could discover.

Would using a different tag for hiding (or should I say removing) an input cell be sufficient (see for example https://jupyterbook.org/en/stable/interactive/hiding.html#removing-code-cell-content)?

It would very helpful if you could assemble a list of which tags are used in different tools to hide/remove which kinds of cells. This list could then be a basis for deciding what to do in nbsphinx and it could also go into the documentation.

Also, it would help if you could find out what this means (and whether HTML is considered an "exported format"):

https://github.com/jupyter/nbformat/blob/b950f02b9e898b2fb3c7c959e385607942b3c2b8/CHANGELOG.md?plain=1#L390-L391

  These fields should not be used to hide elements in exported
  formats.