Global (input/output/prompt/&c..) filtering for all templates, improve customisation docs

[mpacer]

In talking with @fperez, there was a suggestion that the feature that most people want to have integrated in terms of "filtering" is not a purely tag based, but globally.

This takes care of

• input filtering (TemplateExporter.exclude_input=True)
• output filtering (TemplateExporter.exclude_output=True)
• input prompt filtering (TemplateExporter.exclude_input_prompt=True)
• output prompt filtering (TemplateExporter.exclude_output_prompt=True)
• markdown cell filtering (TemplateExporter.exclude_markdown=True)
• code cell filtering (TemplateExporter.exclude_code=True)
• raw cell filtering (TemplateExporter.exclude_raw=True)
• unknown cell filtering (TemplateExporter.exclude_unknown=True)

It also creates a new command line option --no-prompt which turns off input and output prompts (a commonly asked-for feature).

By intervening at the basic skeleton that underpins the rest of our templates, this allows us to operate in a output generic format.

Caveat: In many places we seem to write custom input/output prompts and not use the skeleton's prebuilt structure. I'm not sure why this is, but I did my best to catch all of them. If there are any others they can be cleaned up in later work.

I wanted to document these features more than just with the help option for the configurable, which lead to a substantial editing of customizing.ipynb (which in turn led to smaller edits of example.ipynb's metadata).

[takluyver]

Overall, this looks good to me.

[takluyver]

Interface question - do we want the settings to be exclude_* with default False, or include_* with default True? I don't have a strong preference, but it's worth considering.

[mpacer]

I chose the internal logic to be include and the user facing logic to be exclude.

If we think of the default as what was already there, everything is included. Thus if people want something different they should have to explicitly exclude it.

[takluyver]

It's not immediately obvious from the names and the help strings how exclude_input and exclude_code differ.

[takluyver]

Aha, looking at the template structure code below, it looks like exclude_code excludes both the code and the output from that code.

I'd lean towards leaving the exclude_code option out for now, and let people who do want that specify exclude_input and exclude_output. Without code or output, there doesn't seem that much point in using a notebook in the first place. It's easy to add the option back later if there is demand for it.

[mpacer]

When @fperez and I spoke Monday, the suggestion was that this was a use case that people might want (extracting only the markdown of their document).

Furthermore, I don't think it's intrinsically harmful to include.

One potential use case would be to write a report with the figures saved to disk with explicit invocations of the figures inline with the text (or, for example, in raw cells with figure calls). That would allow people to specify labels and captions from within their notebooks which would solve, for example, this post to the jupyter group.

[minrk]

Would it be clearer for the exclude_<cell_type> flags to be exclude_code_cell, etc.? I think that would resolve the ambiguity of exclude_code and exclude_input.

[mpacer]

I only changed code rather than anything else as there weren't other ambiguities and this way the options are shorter to invoke.

[minrk]

This is awesome, thanks @mpacer!

[mpacer]

@takluyver @minrk I made the suggested change, what else needs to be done?

[minrk]

Great, thanks @mpacer!

[urbandw]

The --no-prompt option is working for me when the output type is python, but not script. Specifically, when a converting an .ipynb file whose only cell contains 2+2,

jupyter nbconvert --to script --no-prompt filename produces a filename.py with the following contents:

# coding: utf-8

# python

# In[1]:


2+2

whereas

jupyter nbconvert --to python --no-prompt filename produces filename.py with

# coding: utf-8

2+2

I would be happy to use --to python as part of my post_save_hook except that I would like it to work for both python and R notebooks, and --to script correctly handles the output file type. Any help much appreciated. Package versions as follows:

jupyter_client 5.2.2
jupyter_core 4.4.0
jupyterlab 0.31.8
jupyterlab_launcher 0.10.5
nbconvert 5.3.1