plenoptic_presentations

Presentations about the plenoptic software package. These presentations are all reveal.js presentations built from markdown files found in their respective folders, with the website built using github pages.

This repo also includes some code used to generate figures.

See notes for notes on how to improve presentations.

Build locally

This repository uses jekyll to build reveal.js presentations from markdown files and svg images. You will need to install jekyll locally (see below), and reveal.js just needs to be present where expected. To do so, you can clone this repository with git clone --recurse-submodules [email protected]:plenoptic-org/plenoptic_presentations.git. If you've already cloned this repository, run git submodule init; git submodule update to check out the proper version.

For jekyll, install Ruby, then run bundle install from this directory to install jekyll and all necessary components (if you get an error when doing this, run gem install bundler first), then run bundle exec jekyll serve to build and serve the website locally. In your browser, navigate to the address shown in the terminal (probably localhost:4000/)

Render code

This repo includes a script, scripts/render_code.py, which can be used to make writing code in the markdown files easier. For all of this, see 2025-05-16_vss-symposium/ for an example.

• It is run during every github pages build.
• To activate for a given presentation, include render.md in the markdown value of your yml frontmatter in slides.html, e.g., markdown: slides-render.md .
• The script does three things in the following order:

  • Allows the insertion of code from other files. Any code block formatted like:

    ```python doctest:path/to/file.py:function
    ```
    

    will have its contents replaced with the docstring of the function named function in path/to/file.py (note that the code block has to be empty!). This is expected to be formatted like a standard python doctest, and the expected use is to run these scripts from the commandline (python -m doctest path/to/file.py), and using render_code.py to insert the source. You must manually insert any outputs. Any lines that have ignore in them will be excluded from the output.

  • Markdown code blocks will be converted to html, preserving any attributes. That is:

    ```python data-line-numbers
    import plenoptic
    ```
    

    Will get converted to:

    <pre><code class="language-python" data-line-numbers data-trim>
    import plenoptic
    </code></pre>
    

    Note that we always add data-trim.

  • Any code blocks that have a line before them formatted like {: (.*)} will be wrapped in a div containing the contents of the curly braces. This is apply additional classes or styling.

When run on an input file named slides.md ,the script will produce a file named slides-render.md (in general, appending -render before the .md file extension), which is the name of the file that should be in the frontmatter of slides.html.

Caution

For some reason, the rendering gets weird if there are too many blank newlines around the code blocks. See 2025-05-16_vss-symposium/slides.md for a working example: a single empty line before and after the <div> that is wrapped around the code block.

Render automatically during development

While writing presentations, it's useful to start a jekyll server with bundle exec jekyll serve --livereload, which will rebuild the presentations whenever a file is updated. In order to also run the scripts/render_code.py script whenever the input is updated, you can make use of inotify-wait (part of the inotify-tools package):

inotify-wait --monitor --event modify slides.md | while read FILENAME EVENT; do
  python ../scripts/render_code.py $FILENAME
end

note that the above should be run within the presentation's folder.

Linked images

Some of the svgs used in the presentations include links to other images found in the assets/ directory, which tends to improve performance over embedding them directly (especially for e.g., plots with many elements). The "including" svg file will contain a line like xlink:href="other_image.svg"; because both svg files live in the assets directory but the slides markdown lives one above it, the browser will be unable to find other_image.svg. To correct this, run: correct_linked_paths.py including_image.svg, which will prepend assets/ to any paths that need it (it is safe to run this script multiple times on the same file). Note that this will break the path to other_image.svg in inkscape, which may make editing including_image.svg more difficult.

This script is run on all svg images found in assets/ folders during the build process and will work for embedded files that end with any of svg,jpg,jpeg,png.

Assets

The assets for these presentations (images, movies) are saved in this OSF project. The script scripts/osf_files.py is provided to ease the upload and download of them as necessary. It requires python 3 with click and tqdm installed (run pip install click tqdm).

Package and upload

To package and upload, the osfclient must also be installed. See that link for setup. The project name for the assets is admxn.

Then, to package run python scripts/osf_files.py package-assets PRESENTATION_DIR/assets/ to create a tarball containing the contents of that directory at the path PRESENTATION_DIR/assets.tar.gz. It's recommended you examine the contents of this tarball (with tar tvf PRESENTATION_DIR/assets.tar.gz) to make sure it contains what you expected.

To upload, run python scripts/osf_files.py upload PRESENTATION_DIR/assets.tar.gz. Depending on how you configured the OSF client, it may ask for your password (or give you permission denied if you do not have upload permissions for the project). (This will not delete the tarball afterwards.)

Download

Anyone can download the assets and it does not require the osfclient being set up.

To do so, run python scripts/osf_files.py download PRESENTATION_DIR, which will download the tarball, extract its contents, and then delete it. If you have a local assets/ directory with the same name as those you're downloading and a more recent modification date, the script will ask if you'd like to extract the contents (potentially overwriting local changes). If you choose not to, the tarball will be left locally for you to examine.

You may also run python scripts/osf_files.py download all, which will download and extract all tarballs.

Licensing

The code found in this repo is licensed the MIT License while all text and images found in the presentations, as well as the presentations themselves are licensed under CC-BY-SA 4.0 (see here for human-readable summary, but in essence, you are free to copy and reuse any components, including the whole presentations, as long as you credit the original authors and share your material under the same (or a compatible) license).