This is a Jupyter extension that shows a list of example notebooks that users can easily preview and copy for their own use.
The targeted application is a JupyterHub deployment, where it is useful to distribute a collection of curated examples or templates and make it possible for hub uses to quickly share examples.
A new "examples" page lists notebooks from some configured directory, showing a title and description gleaned from notebook metadata. For each notebook there are two buttons, "preview" and "use".
Examples are sorted into "reviewed," curated examples and "unreviewed" examples.
Clicking "preview" shows a static HTML version of the notebook, optionally including some example output.
Clicking "use" opens a dialog box to prompt user for a filename or filepath (relative to their home dir).
On the notebook toolbar, a new "share as example" button (the "paper airplane" icon at right) submits the notebook to the list of "unreviewed" examples.
Optionally, you can add a custom title and summary (as shown in the example) by editing the notebook metadata (Edit > Edit Notebook Metadata) and adding "title" and "summary" to the JSON. If these are not present, nbexamples displays the notebook's filepath instead.
- notebook >=4.2
Assuming you want to install the extension into a conda environment, virtual environment, or system-wide environment:
python setup.py install jupyter nbextension install --py nbexamples --sys-prefix jupyter nbextension enable --py nbexamples --sys-prefix jupyter serverextension enable --py nbexamples --sys-prefix
Set the location of the example notebooks to be distributed on the command line when starting Jupyter Notebook:
jupyter notebook --Examples.reviewed_example_dir='/opt/jupyter/examples/reviewed' \ --Examples.unreviewed_example_dir='/opt/jupyter/examples/unreviewed'
Alternatively, set these values in a
jupyter_notebook_config.py file in one
of the config directories listed when you run
c.Examples.reviewed_example_dir = '/opt/jupyter/examples/reviewed' c.Examples.unreviewed_example_dir = '/opt/jupyter/examples/unreviewed'
The intention is that
unreviewed_examples is a globally-writable directory.
Notebooks should be reviewed and promoted to a read-only
If you have conda installed, run the following to create and use an isolated dev environment.
make dev-env source activate nbexamples-dev make notebook
Any changes you make to the static assets (JS, CSS) are immediately available on browser refresh. Any changes you make to the Python require a notebook server restart.
/tree#examplesis the Examples tab on the user's home page
/examplesreturns JSON that populates the contents of that tab
/examples/preview?example_id=xpcs.ipynbshows a static HTML preview (similar to nbviewer)
/examples/fetch?example_id=xpcs.ipynb&dest=my-xpcs.ipynbmakes a "clean" copy of the notebook in the user's home directory, stripping out the example output
/examples/submit?example_id=my-new-example.ipynbcopies a notebook into a shared, globally-writable directory of "unreviewed" examples
This project is indebted to the nbgrader project, a related (and much more complex!) application.