Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 23 commits into from
Apr 4, 2017

Conversation

mpacer
Copy link
Member

@mpacer mpacer commented Mar 22, 2017

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).

Copy link
Member

@takluyver takluyver left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, this looks good to me.

@@ -163,6 +163,31 @@ def _template_file_default(self):

#Extension that the template files use.
template_extension = Unicode(".tpl").tag(config=True, affects_environment=True)

exclude_input = Bool(False,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@@ -163,6 +163,31 @@ def _template_file_default(self):

#Extension that the template files use.
template_extension = Unicode(".tpl").tag(config=True, affects_environment=True)

exclude_input = Bool(False,
help = "This allows you to exclude code cell inputs from all templates if set to True."
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

help = "This allows you to exclude output prompts from all templates if set to True."
).tag(config=True)

exclude_code = Bool(False,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@minrk
Copy link
Member

minrk commented Mar 28, 2017

This is awesome, thanks @mpacer!

@mpacer mpacer added this to the 5.2 milestone Apr 4, 2017
@mpacer
Copy link
Member Author

mpacer commented Apr 4, 2017

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

@minrk
Copy link
Member

minrk commented Apr 4, 2017

Great, thanks @mpacer!

@urbandw
Copy link

urbandw commented Mar 19, 2018

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants