EuroPi icon indicating copy to clipboard operation
EuroPi copied to clipboard

Add list of scripts with descriptions and links to the contrib readme

Open djmjr opened this issue 2 years ago • 5 comments

Quick pass at making useful summary of scripts for the contrib directory readme. Used the Discord #euro-pi scripts channel by @roryjamesallen for most of the content. I also added new scripts in the directory along with descriptions based on their documentation .md files. Also added links to the documentation and script.

Eventually this should be generated programatically, but I don't have those skills yet and wanted to get something out here to test formatting.

djmjr avatar Sep 09 '22 04:09 djmjr

One more thing I think would be great to include attribution to the original script author and any contributors of bug fixes/improvements to those scripts. You should be able to find that in the header or md file associated with each script.

Another factor to consider is how we want to approach maintaining this list. Is this intended to be comprehensive of all scripts or a "glimpse into some of the interesting scripts available". Personally, I'm leaning to the latter and in favor of omitting some of the smaller, more PoC scripts like CoinToss, HelloWorld, Diagnostics and Scope.

We did mention the idea automating the generation of a list of scripts, but I think having a manual curation of scripts is an excellent first step. Thanks for putting this together!

awonak avatar Sep 09 '22 14:09 awonak

Thanks for the feedback! My thought with getting this list together was so that users wouldn't have to click through each of the .md files to figure out what a script did. For that use case I think it's useful to have the proof of concept scripts in there (esp since they show up in the menu.py). On the other hand, it does clutter up the list, and maybe they should be relegated to a different area at the bottom of the page (I'm embarrassingly unfamiliar with markdown, so I'm not sure if there's a way to show/hide content). I'll look into that. I'll work on adding attribution for the scripts. I had also considered adding the self-reported categories, but didn't want to clutter it up too much. I'll see what I can do.

djmjr avatar Sep 09 '22 22:09 djmjr

Finished adding contributors and labels to each entry. Also moved the utility/example scripts to a collapsible section at the bottom.

For contributors, I listed all listed contributors to the .py or .md file, in order of contribution. For labels, I used the self-reported labels with no changes. Eventually we should probably normalize the labels.

I think the automatic generation of this kind of list is a great end goal, and will require some consistent formatting in the script documentation files. Another possible final state could be a mobile-friendly html page that will allow people to search for, review, select, and get instructions for the scripts.

djmjr avatar Sep 10 '22 03:09 djmjr

This looks great, it's a much nicer way of looking at all the scripts than the Discord channel (to be honest I think I will delete the channel once this is merged as it is much less reliable when it comes to version control, whereas this can be lumped with the release steps.

Having a separate section for proof of concept scripts is really neat, and it pushes the interesting ones to the top which is what we want for first time viewers!

LGTM unless anyone else has comments or changes I'm happy to merge now!

roryjamesallen avatar Sep 19 '22 15:09 roryjamesallen

One last comment - I like how the script authors have been added, but I'm having second thoughts about the additional "contributors". I feel like the script author should receive the majority of attribution and listing the additional contributors feels like its taking away from that.

Would you mind removing the contributors and only listing the author for each script?

With that change, LGTM! Thanks for adding this!

awonak avatar Sep 19 '22 15:09 awonak