Package: jnp
title: README
author: Jan-Michael RyeSynopsisjnp is a command-line tool and Python package for creating presentations withJupyter Notebooks. It automates the process of converting notebooks to slides withnbconvertand provides some custom CSS to make the slides look nicer.Examplesjnp example presentation.Hydronaut tutorial.Installationjnp can be installed from thePython Package Indexviapipand similar Python package installers:# Uncomment to first create a virtual environment.# python3 -m venv venv# source venv/bin/activate# pip install -U pippipinstall-UjnpIt can also be installed from source:# Uncomment to first create a virtual environment.# python3 -m venv venv# source venv/bin/activate# pip install -U pipgitclone'https://gitlab.inria.fr/jrye/jnp.git'pipinstall-U./jnpIf you use a virtual environment, you will also need to install an IPython kernel in it to use it within Jupyter Lab.# After activating the custom environment.pipinstall--upgradeipykernel
ipythonkernelinstall--user--name=jnp_venvSelect thejnp_venvkernel for your presentation notebooks.UsageCommand-Line Utilityjnp provides a command-line utility (jnp) that will read Jupyter notebooks and related files in an input directory and publish them to presentations in an output directory. The notebook files must be located in a subdirectory namednotebooksin the input directory. Other files in the input directory can be organized arbitrarily.For each notebook in the input directory, jnp will export slides withnbconvertand customize the output with modified HTML, CSS and Javascript. All other files in the input directory will be copied to equivalent subpaths in the output directory, along with jnp's internal CSS files. An index page will also be generated in the root of the output directory.As a demonstration, the following shows the hierarchy of jnp's example presentation directory, which contains one notebook file and one image:presentations
├── img
│   └── url.svg
└── notebooks
    └── example_presentation_01.ipynbAfter runningjnpwith the default configuration, an output directory with the following file hierarchy will be generated:public
├── css
│   └── jnp
│       ├── index.css
│       ├── main.css
│       ├── reveal.css
│       └── sizes.css
├── img
│   └── url.svg
├── index.html
└── notebooks
    └── example_presentation_01.slides.htmlThe files under the inputnotebooksdirectory are exported to notebook presentations underpubli/notebooks. The image file from the input directory is copied through directly with the same relative path (img/url.svg).In addition to the files generated from the input directory, jnp also create CSS files undercss/jnpand an HTML index page namedindex.html. The index page contains a list of all of the presentations found in thenotebooksdirectory and can serve as a homepage when generating websites with tools such as GitLab Pages. Instructions for customizing the index page are given below.Configuration Filejnp can be configured via an optional YAML file.This file can be generated with the commandjnp --create-config config.yaml. To use it, you must pass it as an argument to jnp (e.g.jnp -c config.yaml).The generated file contains all of the default values for each setting. These are the values used if no configuration file is given or if a setting is omitted from the configuration file. Read the comments in the configuration file to learn what each setting does.# jnp configuration file# The reveal.js slide transition effect. This is passed through to# nbconvert's SlidesExporter.reveal_transition option. For the list of# supported values, see##     https://nbconvert.readthedocs.io/en/latest/config_options.htmltransition:slide# The presentation's aspect ratio.aspect_ratio:1.6# The presentation's width. The presentation will scale to the screen so# this basically just adjusts the size of text and other elements.width:1100# The directory in which to publish the presentations.public_dir:public# The directory containing the Jupyter notebooks and associated files# for the presentation. This directory should contain a subdirectory# named "notebooks" with the Jupyter notebook files (.ipynb file# extension). The rest of the files in the directory will be symlinked# to the output directory when jnp is run.input_dir:presentations# CSS stylesheets to include in the exported HTML slides. These will be# interpretted relative to the public directory.## The default list includes the custom stylesheets provided by jnp.# These can be supplemented, modified or replaced with the users own# stylesheets. The default files will be created automatically when jnp# exports the slides.## For example, "../css/custom.css" will load# "<public_dir>/css/custom.css" from a notebook located in# "<public_dir>/notebooks".stylesheets:-../css/jnp/main.css-../css/jnp/sizes.css-../css/jnp/reveal.css# The default main.css stylesheet supports limited configuration via the# following variables:##     jnp-main-color:#         The main color of the presentation's theme (H1 header#         backgrounds, H2 header text, links, etc.)##     jnp-h1-color:#         The text color of H1 headers displayed on jnp_main_color#         backgrounds.##     jnp-background:#         The CSS background properties (color, image, position, etc.):##         For details, see#         https://www.w3schools.com/cssref/css3_pr_background.php##     jnp-radius:#         Border radius of H1 header backgrounds, code blocks, images,#         etc.css_variables:jnp-background:attachment:fixedcolor:'#ffffff'image:noneposition:centerrepeat:no-repeatsize:100% 100%jnp-h1-color:'#ffcd1c'jnp-main-color:'#1488ca'jnp-radius:10pt# The Pygments syntax highlighting style to use. The list of available# styles can be displayed with the command "pygmentize -L styles". An# online preview of the built-in styles is available here:##     https://pygments.org/styles/pygments_style:default# The index page template file path.index_template:null# The placeholder variable for the list of links in the index template.placeholder:'%NOTEBOOK_LINKS%'Index Pagejnpwill create an index page that lists all of the exported presentations in the output directory. The default index page is a plain HTML list but it can easily be customized with the user's own template.The default template can be generated withjnp --copy-index-template index.html:<html><head><title>Presentations</title><linkrel="stylesheet"href="css/jnp/index.css"/></head><body><divid="frame"><h1>Presentations</h1><ol>%NOTEBOOK_LINKS%</ol></div></body></html>To use a custom template, simply modify the default template or create a new one with a placeholder where the list of links to the notebooks should be inserted. In the configuration file, setindex_templateto the path of the custom file. If necessary, you can also change the placeholder variable by changing theplaceholderfield. When the custom template is loaded, this text will be directly replaced by the HTML list of links to the presentations.Display jnp CSS In NotebookBy default, only the exported presentation use the custom jnp CSS files. If you want to apply the stylesheets to the notebook directly in Jupyter Lab, follow these steps:Copy the internal static jnp files to the input directory (e.g.jnp --copy-static presentations). This will add the CSS files to the input directory.Create a code cell that contains the output ofjnp --html-cell. If a configuration file is given, the output will include user-configured stylesheets (via thestylesheetssetting). The default output only contains internal jnp stylesheets:%%html<linkrel="stylesheet"href="../css/jnp/main.css"/><linkrel="stylesheet"href="../css/jnp/sizes.css"/><linkrel="stylesheet"href="../css/jnp/reveal.css"/>Set the slide type to "skip" to omit it from the output.The stylesheets should be automatically applied once the cell is executed and the document is saved. If not, try refreshing the page. To remove them, simply remove the HTML cell and delete the copied files from the input directory.Hide Cellsjnp provides the following tags to hide cells in the exported presentation:hide_input: input cellshide_output: output cellsIf you want to hide both, set the slide type to "skip".jnp Helpusage: jnp [-h] [-c CONFIG] [--create-config PATH] [--copy-static PATH]
           [--copy-index-template PATH] [--html-cell]

Export Jupyter notebook presentations to a directory.

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        The path to the YAML configuration file. If not given,
                        default paths will be used.
  --create-config PATH  Create a default confuration file at the given path.
                        If the path is "-" then print to STDOUT.
  --copy-static PATH    Copy internal static files to the given path. Use this
                        to create modified copies of the internal files.
  --copy-index-template PATH
                        Copy the internal index template. The template can be
                        used as a starting point for creating a custom index
                        page. If the path is "-" then print to STDOUT.
  --html-cell           Print a Jupyter notebook HTML cell that can be used to
                        display CSS styles while editing the notebook. Copy
                        and poste the content to a separate "code" cell and
                        execute it. Copy the static files to the input
                        directory with --copy-static so that Jupyter Lab can
                        find them.Python PackageAlthough the jnp Python package is not intended for general usage beyond providing thejnpcommand-line utility, it does provide some functionality for Jupyter notebooks. The package's online documentation is availablehere.BugfixesThe submodulejnp.bugfixesprovides a fix for a bug in Jupyter notebooks' syntax highlighting in the output files. To use it in a notebook, simply import the customizedCodeclass by creating a code cell with the following content:# Fix syntax highlighting bug. Set the slide type to "Skip".fromjnp.bugfixesimportCodeCommand OutputThe submodulejnp.notebookprovides the functiondisplay_command_outputthat can be used to insert highlighted command output in a notebook cell. It accepts a command (as a list) and an optionallanguagekeyword parameter for specifying the highlighting language. For example, the following cell would insert the default jnp YAML configuration file in the notebook:fromjnp.notebookimportdisplay_command_outputdisplay_command_output(['jnp','--create-config','-'],language='yaml')TroubleshootingMissing Module: notebook.baseUsers may encounter the following error when using older versions of Jupyter:ModuleNotFoundError: No module named 'notebook.base'If Jupyter cannot be upgraded, downgrade thenotebookto version 6.4.12:pip install -U notebook==6.4.12It may also be necessary to downgradetraitletsas well:pip install -U traitlets==5.9.0For details, see thediscussion on Stack Overflow.Tips and TricksOffline SlidesThe exported slides use Javascript from third-party websites such asrevealjs.comand will therefore not display correctly without an internet connection (unless your browser or system uses local caching). If you need to ensure that a presentation displays correctly offline, open it in a browser that supports saving complete webpages. For example, in both Firefox and Chrome you can right-click on the page, select "Save as..." and then select the format "Web Page, Complete".Scriptsgenerate_url_qrcode.sh- Generate an SVG image with a QR code for the given URL. If no argument is give, use jnp's GitLab URL.jupyter-lab-venv.sh- Create a virtual environment, install the required packages and run Jupyter Lab. All arguments are passed through to thejupyter-labcommand.publish.sh- Export the example presentation and theSphinxdocumentation to the public directory for GitLab pages.update_notebook.sh- Update one or more notebooks by running all cells and overwriting the original file. This should only be run within the environment configured byjupyter-lab-venv.sh.update_readme.py- Update command output in the README file.Further Readingjupyter homepage- The home of Jupyter Lab etc.nbconvert documentation- Documentation of the command-line tool used to convert Jupyter notebooks to presentations.reveal.js website- The framework used by nbconvert to create the presentations.Configuring the Notebook for slides presentations- A brief explanation of how to change the slide types of notebooks cells. Ignore the part about dejavu as it is not relevant to exporting presentations with jnp.W3Schoolsprovides great documentation ofHTML tagsandCSS propertiesfor creating custom HTML. You can find lots of inspiration for new layouts there.