From 2b74ad8abb4866105445af7ad427ea7c0fcaa836 Mon Sep 17 00:00:00 2001 From: M Pacer Date: Wed, 10 Jan 2018 12:54:27 -0800 Subject: [PATCH 1/7] change default for slides to direct to the cdn rather than locally, quick fix for #702 --- nbconvert/exporters/slides.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nbconvert/exporters/slides.py b/nbconvert/exporters/slides.py index 6f22b1776..8be0daada 100644 --- a/nbconvert/exporters/slides.py +++ b/nbconvert/exporters/slides.py @@ -90,7 +90,7 @@ def _reveal_url_prefix_default(self): warn("Please update RevealHelpPreprocessor.url_prefix to " "SlidesExporter.reveal_url_prefix in config files.") return self.config.RevealHelpPreprocessor.url_prefix - return 'reveal.js' + return 'https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.1.0' reveal_theme = Unicode('simple', help=""" From ff3ef1e4a0e5c3ecb21546d850af300f67d6454b Mon Sep 17 00:00:00 2001 From: Thomas Kluyver Date: Mon, 15 Jan 2018 15:49:03 +0000 Subject: [PATCH 2/7] Clarify that reveal.js 3.x is needed Closes gh-702 --- docs/source/usage.rst | 2 +- nbconvert/exporters/slides.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 39e4a9b2d..cf95e7674 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -96,7 +96,7 @@ Reveal.js HTML slideshow ``--post serve`` on the command-line. The ``serve`` post-processor proxies Reveal.js requests to a CDN if no local Reveal.js library is present. To make slides that don't require an internet connection, just place the - Reveal.js library in the same directory where your_talk.slides.html is + Reveal.js library (version 3.x) in the same directory where ``your_talk.slides.html`` is located, or point to another directory using the ``--reveal-prefix`` alias. .. note:: diff --git a/nbconvert/exporters/slides.py b/nbconvert/exporters/slides.py index 8be0daada..e528b4913 100644 --- a/nbconvert/exporters/slides.py +++ b/nbconvert/exporters/slides.py @@ -77,7 +77,7 @@ class SlidesExporter(HTMLExporter): reveal_url_prefix = Unicode( help="""The URL prefix for reveal.js. - This can be a a relative URL for a local copy of reveal.js, + This can be a a relative URL for a local copy of reveal.js (version 3.x), or point to a CDN. For speaker notes to work, a local reveal.js prefix must be used. From 6fcd4a6191224bfb84007dead4c45ecdb14bb49b Mon Sep 17 00:00:00 2001 From: Thomas Kluyver Date: Thu, 18 Jan 2018 10:36:52 +0000 Subject: [PATCH 3/7] Instructions for fetching reveal.js 3.6.0 --- docs/source/usage.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index cf95e7674..3c6a0803d 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -99,6 +99,15 @@ Reveal.js HTML slideshow Reveal.js library (version 3.x) in the same directory where ``your_talk.slides.html`` is located, or point to another directory using the ``--reveal-prefix`` alias. + To get a compatible version of revealjs in the current folder: + + .. code-block:: shell + + git clone https://github.com/hakimel/reveal.js.git + cd reveal.js + git checkout 3.6.0 + cd .. + .. note:: In order to designate a mapping from notebook cells to Reveal.js slides, From b83a599f62bbded2e6d1a3773d30b042ef78b9c4 Mon Sep 17 00:00:00 2001 From: Thomas Kluyver Date: Fri, 19 Jan 2018 12:24:20 +0000 Subject: [PATCH 4/7] Use reveal 3.5 for consistency --- docs/source/usage.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 3c6a0803d..6d65d6b2e 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -105,7 +105,7 @@ Reveal.js HTML slideshow git clone https://github.com/hakimel/reveal.js.git cd reveal.js - git checkout 3.6.0 + git checkout 3.5.0 cd .. .. note:: From 2f508ca9f13457fb5c074345196f45b7067e59a1 Mon Sep 17 00:00:00 2001 From: M Pacer Date: Tue, 23 Jan 2018 10:06:19 -0800 Subject: [PATCH 5/7] update version of reveal to 3.5 --- nbconvert/exporters/slides.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nbconvert/exporters/slides.py b/nbconvert/exporters/slides.py index e528b4913..8c1d212d7 100644 --- a/nbconvert/exporters/slides.py +++ b/nbconvert/exporters/slides.py @@ -90,7 +90,7 @@ def _reveal_url_prefix_default(self): warn("Please update RevealHelpPreprocessor.url_prefix to " "SlidesExporter.reveal_url_prefix in config files.") return self.config.RevealHelpPreprocessor.url_prefix - return 'https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.1.0' + return 'https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.5.0' reveal_theme = Unicode('simple', help=""" From 880a388d5ad3931ff07ad0b7b5b37555ea536b76 Mon Sep 17 00:00:00 2001 From: M Pacer Date: Thu, 25 Jan 2018 12:47:04 -0800 Subject: [PATCH 6/7] modify help string to point at the usage docs. --- nbconvert/exporters/slides.py | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/nbconvert/exporters/slides.py b/nbconvert/exporters/slides.py index 8c1d212d7..522534125 100644 --- a/nbconvert/exporters/slides.py +++ b/nbconvert/exporters/slides.py @@ -76,11 +76,16 @@ class SlidesExporter(HTMLExporter): """Exports HTML slides with reveal.js""" reveal_url_prefix = Unicode( - help="""The URL prefix for reveal.js. - This can be a a relative URL for a local copy of reveal.js (version 3.x), - or point to a CDN. - - For speaker notes to work, a local reveal.js prefix must be used. + help="""The URL prefix for reveal.js (version 3.x). + This defaults to the reveal CDN, but can be any url pointing to a copy + of reveal.js. + + For speaker notes to work, this must be a relative path to a local + copy of reveal.js: e.g., "reveal.js". + + See the usage documentation + (https://nbconvert.readthedocs.io/en/latest/usage.html#reveal-js-html-slideshow) + for more details. """ ).tag(config=True) From a6079579baf67b5d95daa6959bead65072ab3af4 Mon Sep 17 00:00:00 2001 From: M Pacer Date: Thu, 25 Jan 2018 14:54:38 -0800 Subject: [PATCH 7/7] Improve usage docs for the reveal slideshow emphasize that the key feature for speaker notes is a local copy. Give an example of how to set up speaker notes. --- docs/source/usage.rst | 85 ++++++++++++++++++++++++----------- nbconvert/exporters/slides.py | 3 +- 2 files changed, 62 insertions(+), 26 deletions(-) diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 6d65d6b2e..2c6dd84bc 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -92,31 +92,66 @@ Reveal.js HTML slideshow * ``--to slides`` This generates a Reveal.js HTML slideshow. - It must be served by an HTTP server. The easiest way to do this is adding - ``--post serve`` on the command-line. The ``serve`` post-processor proxies - Reveal.js requests to a CDN if no local Reveal.js library is present. - To make slides that don't require an internet connection, just place the - Reveal.js library (version 3.x) in the same directory where ``your_talk.slides.html`` is - located, or point to another directory using the ``--reveal-prefix`` alias. - - To get a compatible version of revealjs in the current folder: - - .. code-block:: shell - - git clone https://github.com/hakimel/reveal.js.git - cd reveal.js - git checkout 3.5.0 - cd .. - - .. note:: - - In order to designate a mapping from notebook cells to Reveal.js slides, - from within the Jupyter notebook, select menu item - View --> Cell Toolbar --> Slideshow. That will reveal a drop-down menu - on the upper-right of each cell. From it, one may choose from - "Slide," "Sub-Slide", "Fragment", "Skip", and "Notes." On conversion, - cells designated as "skip" will not be included, "notes" will be included - only in presenter notes, etc. + +Running this slideshow requires a copy of reveal.js (version 3.x). + +By default, this will include a script tag in the html that will directly load +reveal.js from a CDN. + +However, some features (specifically, speaker notes) are only available if you +use a local copy of reveal.js. This requires that first you have a local copy +of reveal.js and then that you redirect the script away from your CDN to your +local copy. + +To make this clearer, let's look at an example. + +.. note:: + + In order to designate a mapping from notebook cells to Reveal.js slides, + from within the Jupyter notebook, select menu item + View --> Cell Toolbar --> Slideshow. That will reveal a drop-down menu + on the upper-right of each cell. From it, one may choose from + "Slide," "Sub-Slide", "Fragment", "Skip", and "Notes." On conversion, + cells designated as "skip" will not be included, "notes" will be included + only in presenter notes, etc. + +Example: creating slides w/ speaker notes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Let's suppose you have a notebook ``your_talk.ipynb`` that you want to convert +to slides. For this example, we'll assume that you are working in the same +directory as the notebook you want to convert (i.e., when you run ``ls .``, +``your_talk.ipynb`` shows up amongst the list of files). + +First, we need a compatible version of reveal.js in the current folder run the +following commands inside the directory: + +.. code-block:: shell + + git clone https://github.com/hakimel/reveal.js.git + cd reveal.js + git checkout 3.5.0 + cd .. + +Then we need to tell nbconvert to point to this local copy. To do that we use +the ``--reveal-prefix`` command line flag to point to the local copy. + +.. code-block:: shell + + jupyter nbconvert your_talk.ipynb --to slides --reveal-prefix reveal.js + +This will create file ``your_talk.slides.html``, which you should be able to +access with ``open your_talk.slides.html``. To access the speaker notes, press +``s`` after the slides load and they should open in a new window. + +This should also allow you to use your slides without an internet connection. + +If this does not work, you can also try start a server as part of your nbconvert +command. To do this we use the ``ServePostProcessor``, which we activate by +appending the command line flag ``--post serve`` to the above command. This +will not allow you to use speaker notes if you do not have a local copy of +reveal.js. + .. _convert_markdown: diff --git a/nbconvert/exporters/slides.py b/nbconvert/exporters/slides.py index 522534125..fe1576267 100644 --- a/nbconvert/exporters/slides.py +++ b/nbconvert/exporters/slides.py @@ -101,7 +101,8 @@ def _reveal_url_prefix_default(self): help=""" Name of the reveal.js theme to use. - We look for a file with this name under `reveal_url_prefix`/css/theme/`reveal_theme`.css. + We look for a file with this name under + ``reveal_url_prefix``/css/theme/``reveal_theme``.css. https://github.com/hakimel/reveal.js/tree/master/css/theme has list of themes that ship by default with reveal.js.