Change the IPython slides defaults with an IPython config file

English   |   Código fuente   |   Minimap

Some people are asking me how to change the IPython slides's defaults. You can see the description of the request here. Essentially, he wants to change the default transition between the slides.

To solve this question, we introduce the notion of IPython config files, which let us easily change things inside IPython.nbconvert (the library where the IPython slides lives) to achieve our desires, at least in the slideshow generation issue ;-)

First of all, you need to know some details:

  • The IPython slides are generated using a series of Jinja templates, so we are going to modify one of the templates to render the slideshow accordingly with our own defaults.
  • The IPython.nbconvert library was developed taking into account the need from some users to use customized things (where thing will be a template in this case, but we could modify other parts of IPython.nbconvert, probably I will cover this ideas in other posts).
  • The IPython machinery is very configurable through a Traitlets system! And because of this feature, IPython.nbconvert is able to take a custom config file and use it to render our IPython slides (or any other IPython.nbconvert formats).

OK, can you show me an example config file? Of course, here we go:

In [1]:
!cat /media/datos/Ejemplos/slides_config.py
  Click me to hide the output 
c = get_config()

c.Exporter.template_file = 'default_transition'

From the IPython docs:

A configuration file is simply a pure Python file that sets the attributes of a global, pre-created configuration object. This configuration object is a Config instance. While in a configuration file, to get a reference to this object, simply call the get_config() function. We inject this function into the global name-space that the configuration file is executed in,

So, we have to call the get_config() function and then use a custom template called 'default_transition' and assign it to c.Exporter.template_file attribute.

Oh, we need to write the 'default_transition' template yet, so here we go... again:

In [2]:
!cat /media/datos/Ejemplos/default_transition.tpl
  Click me to hide the output 
{%- extends 'slides_reveal.tpl' -%}


{% block body %}

{{ super() }}

<script>

Reveal.initialize({

    // Display controls in the bottom right corner
    //controls: true,

    // Display a presentation progress bar
    //progress: true,

    // Push each slide change to the browser history
    //history: false,

    // Enable keyboard shortcuts for navigation
    //keyboard: true,

    // Enable touch events for navigation
    //touch: true,

    // Enable the slide overview mode
    //overview: true,

    // Vertical centering of slides
    //center: true,

    // Loop the presentation
    //loop: false,

    // Change the presentation direction to be RTL
    //rtl: false,

    // Number of milliseconds between automatically proceeding to the
    // next slide, disabled when set to 0, this value can be overwritten
    // by using a data-autoslide attribute on your slides
    //autoSlide: 0,

    // Enable slide navigation via mouse wheel
    //mouseWheel: false,

    // Transition style
    transition: 'concave', // default/cube/page/concave/zoom/linear/fade/none

    // Transition speed
    //transitionSpeed: 'default', // default/fast/slow

    // Transition style for full page backgrounds
    //backgroundTransition: 'default', // default/linear/none

    // Theme
    theme: 'sky' // available themes are in /css/theme

});

</script>

{% endblock body %}

In the first line, {%- extends 'slides_reveal.tpl' -%} tells to the Jinja system that we are going to extend slides_reveal template (the default one, which IPython.nbconvert uses to build our common slides by default). Then, inside the {% block body %}, we call super():

From the Jinja docs:

Super Blocks It’s possible to render the contents of the parent block by calling super.

We did it in this way because we want to render all the parent content and, after that, add our own content, essentially a config script for Reveal.js, calling Reveal.initialize.

OK, I have written a lot of configurable options you can play with, but I only left uncommented (and hence, they will be applied) the transition: 'concave' and theme: 'sky' options with my new choices, you can use your own ones.

Finally, you have to use the IPython.nbconvert library from command line, as usual, but pointing to the IPython config file you pretend to apply:

ipython nbconvert your_talk.ipynb --to slides --post serve --config slides_config.py

And you are done!

NOTE: Don't forget to put your ipynb, slides_config.py and default_transition.tpl files in the same folder where you will run the IPython.nbconvert command.

As you can see, the potentiality of this system (Jinja templating plus a powerful config system) is really big! We can achieve awesome things in a very easy way!

Any help, just let me know!

Addemdum: the use of default_transition.tpl generates an invalid but useful final html document. The cause behind this issue is the script containing the Reveal.initialize function, which is located after the closing body tag. All modern browser render this sort of invalid html witout any difficult. But a commenter arose this issue and I think is important to make it available in the post itself.

Damián

Did you like the content? Great!

Or visit my support page for more information.


Btw, don't forget this blog post is an ipynb file itself! So, you can download it from the "Source" link at the top of the post if you want to play with it ;-)

Comments powered by Disqus