Resources

This page lists web sites, PDF documents, Jupyter notebooks, and Python packages that have been mentioned during the course.

It’s not an attempt to list everything related to each of those topics; just to collect those resources that have already been mentioned into one place.

It is a companion to the Recipes page.

General

Stack Overflow is a community of programmers, and a knowledge base of programming questions and answers. You can search it directly from its site; it also shows up in Google search.

Python

Python References

Learn Python

Python Style Guides

Python Packages

Atom

Atom Reference

Atom Tips

These have moved to Atom recipes.

Atom Packages

https://teletype.atom.io is like Google Docs for Atom. It enables real-time collaborative editing of a single Python file from two or more computers.

Command Line

Bash

Git

Also see Git recipes and Reading Journal instructions.

Git Reference

Learn Git

Git Tutorials From Past Semesters

Git & GitHub presentation (thanks: Chris)

One-page cheat sheet (PDF, thanks: Celine)

Digging Deeper

Markdown

Media

Screen Capture

One of the most impactful ways to show your work in action is to… show your work in action!

For still images, there is a Ubuntu built-in tool called Screenshot that will allow you to capture the entire screen, one window, or a region you select.

There are many options to record video of your screen, but for Ubuntu we recommend you start by trying Peek. To install:

sudo add-apt-repository ppa:peek-developers/stable
sudo apt update
sudo apt install peek

Used sparingly this can be a powerful way to quickly show what you’ve created, but too much can be overwhelming.

You have two options for recording format:

If you saved as a GIF and you need an MP4 to work with video editors like Pitivi, you can use an online converter or convert it using ffmpeg:

ffmpeg -i foo.gif foo.mp4

Troubleshooting: If you get the following error message, there is a problem with peek trying to utilize ffmpeg from inside Anaconda (as opposed to the one installed in the system path).

Using screen recorder backend ffmpeg
Error: Child process exited with code 1
Recording canceled: Command "ffmpeg -f x11grab -show_region 0 -framerate 10 -video_size 498x256 -i :0+941,643 -filter:v scale=iw/1:-1 -codec:v libvpx-vp9 -lossless 1 -r 10 -y /home/pruvolo/.cache/peek/peek7WRLIZ.webm" failed with status 256 (received signal 0).

Output:
ffmpeg version 3.4 Copyright (c) 2000-2017 the FFmpeg developers  built with gcc 7.2.0 (crosstool-NG 8a21ab48)  configuration: --prefix=/home/pruvolo/anaconda3 --disable-doc --enable-shared --extra-cflags='-fPIC -I/home/pruvolo/anaconda3/include' --extra-cxxflags='=-fPIC' --extra-libs='-L/home/pruvolo/anaconda3/lib -lz' --enable-pic --disable-static --disable-gpl --disable-nonfree --disable-openssl --enable-libvpx --cc=/home/pruvolo/anaconda3/bin/x86_64-conda_cos6-linux-gnu-cc --cxx=/home/pruvolo/anaconda3/bin/x86_64-conda_cos6-linux-gnu-c++ --enable-libopus  libavutil      55. 78.100 / 55. 78.100  libavcodec     57.107.100 / 57.107.100  libavformat    57. 83.100 / 57. 83.100  libavdevice    57. 10.100 / 57. 10.100  libavfilter     6.107.100 /  6.107.100  libswscale      4.  8.100 /  4.  8.100  libswresample   2.  9.100 /  2.  9.100Unrecognized option 'show_region'.Error splitting the argument list: Option not found

To fix this, simply run this command from your terminal.

PATH=/usr/bin:$PATH peek

Demo Videos

As part of your final project, your team will create a short demo video. There are two main routes you can take to create this presentation:

Silent film option

From your storyboard, combine a series of still images and/or short GIF clips into a longer animated GIF. There are many tools you can use to do the stitching, but we recommend EZGIF, which can both create and edit GIFs including overlaying text.

Note that your “silent film” doesn’t need to remain silent. You can create an animation using this method, then convert to MP4 video and overlay an audio track following the directions below.

Video option

There are also a huge variety of options for video production, but for this class we recommend the instructions for creating an Ubuntu screen cast (you can ignore the part about creating a virtual machine) using Pitivi. Note that you can also use this flow to create a “silent film” with a bit more control.

Recording audio

Since it’s difficult to get a demo and your narration right at the same time, we recommend that you first create your video, then record an audio voiceover using Audacity, and finally compose the two using Pitivi.

Find a quiet place to record your audio. We also have quality studio microphones you can check out rather than using your laptop’s microphone.

If you’d like to include a “talking head” video clip of your team members, you can record it using the built-in Ubuntu webcam app called Cheese.

If you choose to use background music (by no means necessary), make sure you select options which are licensed appropriately.

Generating title slides and text overlays

Regardless of what implementation technology you use, you will likely want title cards, transitions, and credits (don’t forget to add your names and give credit to resources you use). There are many options to generate these still images, including:

Jupyter

UML Diagrams

Diagram Types

There are a number of types of UML diagrams. For this class, the most useful are:

Depending on your project, these may also be helpful:

Diagram Type Directories

These online references variously include examples, text descriptions, and discussions of when to use each one.

UML Distilled, by Martin Fowler, is more involved reference that also has a lot of good material for how to think about programming in general. It’s available at the Olin Library.

Making Diagrams

Drawing by Hand

Any of the Olin printer/scanners can mail a scan to you. For a diagram, taking a photo from a recent phone will probably work just as well.

Slide Tools

For simple diagrams, you can get by with the draw tools in PowerPoint, Keynote, or Google Slides.

Diagramming Software

Text-based diagram tools.

PlantUML produces an image from a text description. It can create a variety of different kinds of diagrams, shown on its home page.

Mermaid is (IMO) easier to install and use, and produces several useful diagram types, but not class diagrams.

There are Atom plugins for PlantUML and Mermaid, that display the image in one pane while you edit the text in another. I’ve used the Mermaid plugin.

GraphViz is a general-purpose text-to-graph program. It’s not specific to, and doesn’t know about, class diagrams or UML, but can be used for this. It’s a useful tool to have in your toolbox.

“Reverse-Engineering” Tools

These are tools that create UML diagrams from Python sources.

The PyCharm Python IDE (Integrated Development Environment) has this feature. I’ve heard that quite a few students in the Olin community use PyCharm; I don’t know that any use this feature.

Standalone tools include Epydoc, Pyreverse, and Allen’s own Lumpy. A longer list is here.

These appealing, but I’ve found it more helpfully for understanding a pile of code that has been left, without adequate docs, or your doorstep, than for designing of documenting your own code. Done properly, a diagram is expressive and reflects intent: how you position elements, what you leave out, focus on and emphasize different elements in your design. Just as writing prose documentation for your code can lead you to realize how you should have written it (and cause you to go back and revise it, if you’ve got time), the process of creating a diagrams can help you design your system. Tools that run on code that’s already written, and make diagrams mechanically, don’t come out as well, and deprive you of those benefits.