Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

change default for slides to direct to the reveal cdn rather than locally #732

Merged
merged 7 commits into from
Jan 26, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 60 additions & 16 deletions docs/source/usage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -92,22 +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 in the same directory where your_talk.slides.html is
located, or point to another directory using the ``--reveal-prefix`` alias.

.. 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Excellent


.. 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we mention that the timer inside the speaker notes will only work if you are serving the slides?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok I wasn’t sure why that was I thought I had a weird bug and that the serving was required to coordinate 2 windows… why does the timer only work if you serve the slides but it still allows you to communicate between 2 windows?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why does the timer only work if you serve the slides but it still allows you to communicate between 2 windows?

Good question! I have not researched the cause yet. I just verified the behavior.


This should also allow you to use your slides without an internet connection.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, this is not true... we are loading other things from the internet, such as font-awesome, jquery, require, mathjax... and reveal.js itself load google fonts (although they have a fallback in case of lack of connectivity.
This statement as is can cause confussion, I would prefer to delete it.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was making that claim based on the previous docs:

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.

So at least this isn’t a regression…

Makes me think we should have a way to package something that we can guarantee works in an offline context (e.g., where we download the relevant files to the directory in question since this is a more people would like to use).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes me think we should have a way to package something that we can guarantee works in an offline context (e.g., where we download the relevant files to the directory in question since this is a more people would like to use).

Yep, I was thinking the same, maybe some nbconvert script to download all the files needed?


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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Solid prose here


.. _convert_markdown:

Expand Down
20 changes: 13 additions & 7 deletions nbconvert/exporters/slides.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
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)

Expand All @@ -90,13 +95,14 @@ 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'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we finally accept this change, @mpacer you need to point to reveal 3.5.0 which is the version we already have in the serve postprocessor.

return 'https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.5.0'
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All set!


reveal_theme = Unicode('simple',
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.
Expand Down