hide_input Need better documentation for using with nbconvert

[travis23]

I am trying to get hidden input cells to persist with nbconvert --to html. The documentation in readme could use more detail. As it is, I can't get to where I need to go.

The readme for hide_input states
To export a notebook with hidden cells using nbconvert, you need to add a custom template and a custom filter:

• It would be nice to have an example of the custom template.
• Can I put the custom template in the same location as the .ipynb file?
• Where is the custom filter placed? Does it go in the template or in the jupyter notebook or in a .py?
• Can you provide a sample nbconvert command that utilizes the custom template?

[davidgasquez]

Same here! Would love some updated explanations regarding the template usage. 😄

[juhasch]

We now have docs at http://jupyter-contrib-nbextensions.readthedocs.io/en/latest

I will try to add some more documentation there.

[davidgasquez]

Hey @juhasch, I've been able to use the template if I place all in one folder (template.tpl, config.py, notebook.ipynb and filter.py) and run jupyter-nbconvert --config config.py. I think what is a bit confusing for users right now is where to place all those files to make it system wide.

Thanks for sharing the docs!

[jcb91]

@davidgasquez

I think what is a bit confusing for users right now is where to place all those files to make it system wide

the main install does attempt to alter nbconvert config to include the package's templates directory in install.py#L149-L152, but it's possible that that either didn't happen correctly, or isn't being read.

There's another subtle complication, that if you specify a config with a different filename (e.g. config.py in your example), this changes the default config name that jupyter looks for. That is to say, it will look in the normal jupyter config path as usual, but for files named config.json or config.py instead of the usual jupyter_nbconvert_config.json and jupyter_nbconvert_config.py, which are the ones that our install procedure implements. Which exact file gets altered depends on which of the --user, --sys-prefix or --system flags you pass to the

jupyter contrib nbextensions install

command.

If you want to add your own templates system-wide, you can put them all in a folder (let's say /user/josh/nbconvert_stuff/templates for example), then edit a config file using a python snippet:

from jupyter_contrib_core.notebook_compat import nbextensions
from traitlets.config.manager import BaseJSONConfigManager

user, sys_prefix = True, False
config_basename = 'jupyter_nbconvert_config'
my_templates_directory = '/users/josh/nbconvert_stuff/templates'

config_dir = nbextensions._get_config_dir(user=True, sys_prefix=False)
cm = BaseJSONConfigManager(config_dir=config_dir)
config = cm.get(config_basename)
config.setdefault('Exporter', {}).setdefault('template_path', []).append(
    my_templates_directory)
cm.set(config_basename, config)

adjusting the flags user & sys-prefix to set which config directory you want (the per-user one is user is True, the python sys.prefix one if sys_prefix is True, or the system-wide one if neither is true). Note of course that you may need admin privileges to write to a system-wide config (likely), or a sys-prefix config (dependent on your python setup). Does (any of) that make sense? Let me know whether something like this would be helpful in the docs, we can easily add it. You could of course manually edit a json config file to much the same effect.

[davidgasquez]

Thanks a lot @jcb91! This explanation really helped to understand how everything fits together. I'd say that adding this example to the docs makes no harm and people that were searching for this now have a complete example 😄

Thanks again for the explanation!