cmd2
cmd2 copied to clipboard
python-cmd2
Add video or animated GIF demonstrating cmd2 capabilities
cmd2 has some wonderful features, but some of them are more discoverable than others and it is impossible to show how useful of a tool it is for developers with a short code snippet or static screenshot.
The "front page" README.md would benefit from replacing the static screenshot with a short video or animated GIF.
Here's a starting point to see what kind of functionality we can showcase. This could use some better compression (100MB. Actually, skipping some frames or re-recording at a lower resolution would probably be more effective for reducing file size, I already compressed it a bit)
Too big to upload directly here but here's an imgur link ~~https://i.imgur.com/8gIQXWq.mp4~~ ok just kidding I rendered the gif wrong and it cut out too soon, consider this is a demo instead https://youtu.be/DDU_JH6cFsA
@MarkLalor Thanks for the video! I think it is a good starting point which is much nicer than the static image we have on the front page README.md currently.
Could you possibly submit a PR where the video shows up on the front-page README as a static image with a play button and allows playing it with a click (without having to separately jump to YouTube)? This would be a replacement for the current static PNG image.
In the long run it would be nice to have a video which shows off some of the advanced tab-completion features as well, but this is a nice start.
@tleonhardt I'm not sure how to pull off a play button with Github markdown. I uploaded a Youtube video just for discussion right now since the gif was over 10MB and Github doesn't allow over 10MB in the comments.
I can improve the video before submitting the PR though. You mentioned some of the more advanced tab-completion features? Which features exactly, and how do you think I can demo them? If there's any other features as well I can include them.
Apparently there isn't a built-in way on GitHub or in Markdown to add that play button. One possibility would be to leave the existing static image (or replace it with a similar one) and to modify the link when it is clicked to go to the video. Then we would probably have add some text above the image saying something like "Click the image below to watch a brief video demonstrating the capabilities of cmd2".
cmd2 provides good tab-completion wherever it makes sense. For example, when using shell commands via "!", path completion is automatic. Another example, when using the set command, setting names are completed. But in general, when using one of cmd2's argparse decorators along with cmd2's ACArgumentParser class, lots of things get automatically completed, such as flags, hints get provided, choices can get filled in, etc. There are also some helper methods for basic completion, index-based completion, and flag-based completion. These examples might be good ones to look at for some of these features:
@MarkLalor I modified the front-page README so that if a user clicks on the static image, it takes them to your YouTube video. See how you like that. I'm happy with the basic approach.
If you have some time to improve the video, that would be awesome. Thanks for your help!
@tleonhardt yeah I'll try and use some of your suggestions for showing more tab-completion in the demo. I'm pretty busy lately with school but I've been wanting to contribute here a bit so I'm going to try to pick up some of the easy-to-pick-up tasks like this and documentation whenever I get a little time. I'll probably record another video on the weekend.
I think it's still worth making it a gif ultimately though because cmd2 is a very interactive application, and it's not very obvious that there is a video. And even without that, people are lazy and don't want to open external sites.
@MarkLalor Here's a suggestion. Break it down to 2 different things:
1 - animated gif that's cycles through a handful (~6?) of screenshots showing a terminal session that highlights a few interesting interactions such as: (! commands, pyscript, help output, tab-completion parameter hinting output, etc). Maybe give it a few seconds between screenshots - 5-10 seconds?
2 - Video showing the console interaction with the details of what the screen shots show. This would show the typing, tabbing, display output, etc.
The gif can stay small since it's just a handful of exemplar screen shots. The video would go into the details.
We can link to the video from the gif.
@MarkLalor Thanks again for working on this. Obviously, your school work should come first. There is no rush on any of this. If you get a free moment and feel like working on it, then great. Once you get close to graduation and are looking for a job, feel free to get in touch with any of the cmd2 maintainers, I'm sure they would all be happy to help point you in the right direction of a good company.
I agree that having an animated gif on the front page would still be advantageous over a static image.
@anselor Your suggestion to break it up into a brief animated gif which links to a more detailed video is excellent.
Stumbled on a cool tool called asciinema that looks like it can solve our video/gif/screenshots problem. It records terminal output and plays it back in an embeddable frame. Itr looks like a video, but it's not: it instead captures the output stream of the terminal and plays it back. It's much lighter weight to download, and much easier to produce than a video or an animated gif. It also has the benefit that you can copy text from the playback and paste it into your own terminal session.
asciinema will most likely have to be a link to an uploaded version on their site, since the asciinema2gif doesn't really work most of the time (at least in my experience). I think to embed it in markdown + docs you need to have it converted to gif, or have an embedded link to an uploaded version on their site.
