Package: livecode-streamer
livecode-streamerTool for educators running "live coding" sessions to make their source files and terminal sessions viewable as read-only webpages, so that students can refer back to off-screen commands as reference.This project was originally developed within the context of holdingCarpentries workshopsto teach UNIX shells, git, Python, and R, though it should be generalizable to other programming environments and teaching contexts.For a captioned video overview of the tool, see ourlightning talk from CarpentryCon 2022.UsageRun thelivecode-streamercommand in a background terminal window during your lesson:livecode-streamer [options] WATCH_DIR REMOTE_URIWATCH_DIRis a local directory containing the source files you are working on, andREMOTE_URIis a remote webserver to reflect those documents to. Whenever you save your source files, the script will upload HTML versions of them to the remote server. Students can view these files in their browser, and refresh the page as needed to recieve new content.To stream a shell session, you must use a terminal emulator that supports automatic logging to HTML. This repository contains plugins to do so withTerminator(Linux/MacOS) andHyper(Windows/MacOS/Linux) (see the subdirectories in this repo'sexternal-plugins/folder). On starting a new terminal session, just use one of these plugins to log your session to theWATCH_DIR.Hosting and remote URIsThe most ideal way to host the output of this tool is on a personal web hosting account that allows access over SSH. Most universities provide this service to their faculty and staff, a laUW's shared web hosting. The instructions for setting this account up, unfortunately, vary from institution to institution. Once you have access, though, the value to put inREMOTE_URIwould be the remote destination you would normally put in the second half of anscpcommand (eg:username@servername:remote_path).If suitable institutionally provided web hosting isn't available, there are a few other options:Amazon AWSorMicrosoft Azureobject storage: this script can directly upload contents to an AWS S3 bucket or Azure Blob Storage contianer, both of which can be configured to serve static webpages. The downside of these services is that they are not freeGitHub Pages: You can create a repo on GitHub and have this script automatically push updates to it. This repo can then be served as a website through GitHub's "Pages" feature. This option is free, though GitHub has a soft limit of 10 page updates per hour.In all cases, access credentials are securely stored in your operating system's keychain.Installataion and dependenciesInstall withpip install livecode-streamer[jupyter],
which includes all dependencies needed for basic syntax highlighting, rendering jupyter notebooks, and uploading viascp/rsync.To install with dependencies forallplugins:pip install livecode-streamer[jupyter,git,azure,aws,localhost]Core requirements:Python 3.7+watchdogkeyringpygmentsFor Jupyter notebooks:nbformatnbconvertFor shell sessions, one of the following terminal emulators:Hyperwith thehyper-html-log plugin(Windows/MacOS/Linux)Terminatorwith theterminator-html-log plugin(Linux/MacOS)For generic webspace hosting:rsync (optional)ssh/scpFor hosting on Github Pages:dulwichFor hosting on Azure blob storage:azure-storage-blobFor hosting on AWS S3 buckets:boto3For hosting locally over an ngrok tunnel:pyngrokContributingContributions of bugs, new plugins, or feature suggestions are all welcome. For more information, seeCONTRIBUTING.md.