9.0 KiB

Raw Blame History

Presenting Jupyter Notebooks as On-Brand Slides

Slide Decks ToC

There are multiple ways to create slides for your students using preexisting content or GA templates. Here are your options:

Display Jupyter Notebooks in Slideshow format
Serve Markdown Slides Using Reveal.js on Slides.com, Heroku, or locally
Deliver Markdown Slides using Presentations.ga.
Use Standard Slide Deck Templates (e.g. Powerpoint and Google Slides)

We provide Jupyter notebooks for all of our Data Science materials. You can format these into slides a few different ways.

Jupyter with RISE (on GA brand)
Serving slides locally
Jupyter + Reveal.js + Apache

Option 1: Jupyter with RISE

Using RISE will allow you to present slides using on-brand CSS and styling. RISE is straightforward and works with reveal.js.

By installing the RISE Jupyter extension, you can easily toggle into Reveal.js mode as a slideshow.

Follow the installation instructions to install RISE.

Note: only installation Miniconda on macOS has been tested internally. You may encounter some issues, so please submit a pull request against this document to help others if you have any trouble.
The usage documentation for RISE is comprehensive. Using RISE is fairly straightforward, however, so here are the base steps to not only make your notebook Reveal.js-compatible, but get it GA-branded.
1. Once RISE is installed, make a copy of pandoc/css/theme/ga.css in the same directory as your notebook and name it the same as your notebook but with the css extension.
2. Restart any running notebook servers.
3. You will see a new menu option in the Notebook menu submenu labeled Slideshow: View -> Cell Toolbar -> Slideshow. Toggle this option and each cell will now have a dropdown in the upper-right corner.
4. Use this dropdown to select the slide option for a normal slide, the fragment option for a fragment that appears on the same slide as you move forward, or a subslide that will appear below the slide as you advance. The subslide type is useful for optional information.
5. Use Option-r (macOS) or Alt-r to enter and leave the slideshow presentation.
6. When presented in this manner, the code editors will function. Run the code with shift-enter.
It is possible to export the slideshow in a standalone fashion to provide to students after class.
1. Use the File -> Download as option to download the Markdown file.
2. Follow the Option 3 instructions to convert the rendered HTML file into GA-branded slides by running the pandoc converter on the HTML file.
Note: The code editors will be static code images instead of functional editors. However, you can choose to edit the HTML to embed repl.it iframes if you'd like to maintain the inline-editing experience.

Option 2: Displaying Slides Locally

In short, you'll use the following command: jupyter nbconvert [this_notebook.ipynb] --to slides --post serve. You can read more about that here. For more of a walkthrough, continue reading:

Option 3: Jupyter + Reveal.js + Apache

One of the easiest and best ways to generate slides from your notebooks is to use Reveal.js. Check out the following examples:

When finished with these instructions, go back and get pandoc/css/theme/ga.css to style your slides.

Here's how to Get Started

Apache Setup for Reveal.js
Preparing Slides with Jupyter + Reveal.js

Apache Setup for Reveal.js

In order to get the "presenter mode" to work correctly with Reveal.js slides, you need to setup a basic virtual environment on your local machine in order to serve notes correctly.

There may be other steps required to provide the presenter mode. When in doubt, consult the official documentation.

On OSX

On OSX, the default Apache config files are in /etc/apache2. What you will need to do is add a site config file to the Apache config. In the example below, we'll refer to a sample cohort as dat-sf-1 <--- replace with your own cohort title.

File: /etc/apache2/sites/dat-sf-1.localhost.conf

An example

<VirtualHost *:80>
  ServerName dat-sf-1.localhost
  ServerAlias dat-sf-1.localhost
  DocumentRoot /var/www/htdocs/dat-sf-1.localhost/htdocs

</VirtualHost>

<Directory "/var/www/htdocs/dat-sf-1.localhost/htdocs">
  Options +Indexes
  AllowOverride All
</Directory>

Configuration notes:

ServerName and ServerAlias should be configured to use the domain you setup in your local hosts file.
DocumentRoot defines the document root apache will serve files for this domain (ie: your slides files)
<Directory> elements define the location of your file (slides)
Directory options +Indexes and AllowOverride All allow for the listing of directories and for the use of .htaccess files that will real configuration variables from if you add this file to your directory.

Hosts File

Add this entry to your /etc/hosts file, to resolve your local domain to your local ip 127.0.0.1:

127.0.0.1       dat-sf-1.localhost

Feel free to update the domain entry to whatever you like but make sure you match it correctly to your Apache config above. Entries to this file take hold immediately

Preparing Slides with Jupyter and Reveal.js

Creating slides with Jupyter's iPython notebook isn't bad at all. Some of the benefits of this format is that students can run and follow along, code can be consolidating, and instructors can control which frames get exported as slides.

When exporting slides, the following features can be controlled using the "Slideshow" view from **View > Cell Toolbar > Slideshow**:

The "slideshow" cell types include:

Slide
Subslide
Fragment
Skip
Notes

Slide

A slide cell type is the most common type. The default slide type is "None" so you will have to set this manually when authoring new slides.

Subslide

A subslide belongs to the previously defined slide nearest the subslide. Subslides are accessed via the down key when presenting. See the reveal.js website for the demo of how subslides work. Generally, slides are sequenced from left to right (using the arrow keys), and subslides (as they relate to slides), can be navigated vertically as they are defined below slides. Defining a new slide type will break out of subslides when defined after.

Fragment

Use a fragment when you want a subsection to appear in a slide (defined prior to a fragment), that is revealed after navigating forward. This is useful when you may want to present a question, ask for answers, then revealing the answer on the same slide (the slide that is defined preceding the fragment).

Skip

Skip will omit the cell from the slide deck upon rendering.

Notes

Notes will not display on the slide deck, but will display in the prompter window available when viewing the slide deck -- hotkey "s".

Converting Notebooks

After authoring your notebook with the slideshow settings with chosen celltypes etc, you can easily create these notebooks using this command from terminal:


jupyter nbconvert [the name of your .ipynb file] --to slides

However, in order to use the prompter view, you will have to setup a local web instance. Previously, we created an Apache virtual domain on our local machine, and appended a host entry in our /etc/hosts file called dat-sf-1.localhost, then linked it to our local working copy of our student repo.

In the case for this use case, we use a local copy of the reveal.js library so we end up using this command to update the references in the output slides, to use the local copy of reavel.js:


jupyter nbconvert [the name of your .ipynb file] --to slides --reveal-prefix /reveal.js

Useful Hotkeys

f - Go fullscreen.
s - Presenter mode. Use with a split screen display to view a previous of your slides, and any notes defined after a slide type cell. Super handy!

References

Apache Setup For Reveal.js

9.0 KiB Raw Blame History