GSoC'22

[tushar5526]

Hello to everyone in the py5 community.

I am starting this discussion to discuss the project specifications for the GSOC'22 proposal, as there was no slack or any community chat available.

I have been an avid contributor to p5py (the native python port of Processing) and am well versed with the in and outs of the library.

First of all, py5 is up to a great start and is tackling all the issues we were having in p5py. (like jupyter notebook mode is a demanded feature in p5py)

I was a bit late in discovering py5 as p5py will not be participating in GSOC due to the unavailability of mentors and wasn't aware about py5.

The idea pages for GSOC'22 mention that we will we needing tutorials for py5 and more specifically we are looking for something like the text tutorials

Before starting out the proposal, I have a few doubts regarding the scope of the project and a few other things.

I prefer how p5py did their tutorials section and we could do something similar here. Along with it, we will be needing ports of the same examples preferably for all the py5 modes possible.

I love to hear your thoughts on this to get a good grasp of the scope of the project (like apart from docs, can we include some feature contributions, testing CI-CD setup as well for the library)
@hx2A @tabreturn

Thanks

PS: I loved this writeup on the py5 community and the vision, especially because my open source journey began with processing (p5py) and I am looking to continue learning and contributing through py5 as well.

[hx2A]

Hello @tushar5526 ! Welcome to py5, and thanks for opening this discussion.

as there was no slack or any community chat available

I've thought about that but so far Github discussions, twitter, and Processing discourse have been keeping everyone busy and is working well. I've been advised that having too many options early on can dilute discussion and community growth. We should look into getting a "py5" category on Processing discourse though, because the py5 related subjects keep ending up in other categories and I might be missing some of them.

First of all, py5 is up to a great start and is tackling all the issues we were having in p5py. (like jupyter notebook mode is a demanded feature in p5py)

Thanks! Since py5 uses the Processing jars, there were a lot of features that didn't have to be built from scratch, leaving more time for features like Jupyter integration. As Newton said, "If I have seen further it is by standing on the shoulders of giants". Much respect and appreciation for the Processing team for building Processing in a way that makes py5 possible.

I prefer how p5py did their tutorials section and we could do something similar here.

I don't claim to be an expert in how documentation should be organized but generally I believe in the documentation system used by many other Python libraries. Porting documentation made for other Processing versions into py5 seems like a fast and efficient way to create documentation quickly. I do like that idea. Some adjustments would be needed here and there as in some cases there are new ways of doing things. For example, using np_pixels[] is often a better choice than pixels[].

testing CI-CD setup as well for the library

Right now py5 has no unit tests or CI-CD but that is a high priority, right after OSX fixes (and the release going out in a few days will be a major step forward for addressing this). I do believe it is critical to get CI-CD working because without it it will be hard for me to stay sane and manage pull requests from people adding new features or fixing bugs.

PS: I loved this writeup on the py5 community and the vision, especially because my open source journey began with processing (p5py) and I am looking to continue learning and contributing through py5 as well.

I appreciate your kind words!

[tabreturn]

Thanks for introducing yourself here, @tushar5526, and it's exciting to hear you're interested in the GSoC opportunity.

You and @hx2A have made some excellent points. I'd add that I think it's useful if the tutorial content follows a progression -- from getting started to intermediate -- so that the user might read the tutorial content in sequence to learn programming py5 (and, by extension, Python) from scratch. Some more accomplished person, however, might jump to a specific section.

For my teaching Processing.py (and soon, py5), I find the following structure works well --

1. Installation and getting py5 running
2. Drawing 2D primitives (the basic coordinate system, color, fills, strokes). Note: I use static mode until point 9.
3. Variables (and dealing with different data types -- for creating visual output, of course)
4. Drawing more complicated shapes (curves, vertices, contour functions)
5. Working with text (basics of working with strings and text functions)
6. Conditional statements (if, else, elif to produce visual results)
7. Iteration (while and for loops to produce visual results; break, continue)
8. Randomness (random functions for making tiled patterns)
9. Motion / Animated sketches (the setup() and draw() functions; frame... functions)
10. Transformation (transformation functions, push/pop matrix)
11. Working with lists (standard Python list stuff with visual results)
12. Reading data (CSV files to generate charts)
13. Dictionaries (standard Python dictionary stuff, and maybe loading JSON)
14. Functions (defining function, args, return, etc. to produce visual results)
15. Trigonometry essentials (using trig functions for animated results)
16. Object-Oriented Programming (standard Python OOP stuff with visual results)
17. PVector (combined with OOP to produce visual, animated results)
18. Mouse and Keyboard Interaction

I'm not saying this is the exact structure to follow, but it's a helpful 'flow' if somebody uses py5 for education.

[hx2A]

A set of tutorials that cover those topics would be a great progression for getting people up to speed with py5. It covers all the essentials and would be a great foundation for learning about py5 and Python.

[villares]

Wonderful list, @tabreturn!
The only thing I would do differently would be to introduce some very basic Mouse and Keyboard earlier, after 9, like mouse_x, mouse_y and is_mouse_pressed and is_key_pressed.

[tushar5526]

@tabreturn Thank you for the detailed reply. I have a more concrete structure in my mind now, would try to share a rough draft for the proposal ASAP.

I am thinking of a mixed approach using @tabreturn wonderful list to introduce the features of python language and the standard text tutorials, along with examples that are common in all the Processing ports, as users familiar with processing and coming from other Processing modes would find it better that way.

I am open to more ideas or suggestions as always @villares @hx2A @tabreturn

[hx2A]

Sounds like a great plan. Looking forward to reading this proposal, @tushar5526

[tushar5526]

Hi, @hx2A @tabreturn @villares Here is my first draft of the proposal that I would love you all could review and share some feedback.

py5 GSoC'22 Proposal: Beginner Documentation & Additions

[villares]

@tabreturn has done an amazing job of presenting some examples (with some adaptations and limitations) using http://berinhard.github.io/pyp5js at http://pyde.org/

[tabreturn]

* this is highly experimental and hacked together, @villares -- but perhaps presents one possible approach

[tushar5526]

@villares http://berinhad.github.io/pyp5js is broken.
http://pyde.org/ They are using p5.js behind the scenes, so for static sketches, I will use Thebe or Binder and for other sketches are p5.js display window would do the job.

[villares]

@villares http://berinhad.github.io/pyp5js is broken. http://pyde.org/ They are using p5.js behind the scenes, so for static sketches, I will use Thebe or Binder and for other sketches are p5.js display window would do the job.

Sorry I have missed an 'r': http://berinhard.github.io/pyp5js
It is based on a p5js canvas drawing infrastructure

[tushar5526]

@villares, It looks good, but I am not sure we would be able to integrate it into our static docs website. We will need a separate server to host this.
Apart from that, it does not cover all the Processing APIs, and we will have to use the same variable names and camelCase convention as that of p5.js, this would get confusing for py5 users to follow.

I think using p5.js (and py5, wherever possible) to display the sketch output is still the best way to go about this.

[tushar5526]

Hi everyone.

Thank you everyone for your rigorous reviews and suggestions.
The proposal looks a lot better now, and I will submit it in a day or two.

If there is something else regarding the proposal, I will be glad to take it.

[hx2A]

You are welcome!

The proposal looks good. You make a good point about the JAVA_HOME environment variable. If JAVA_HOME is set, py5 takes this to mean that is the version of Java you want to use. I will mention that in the simple steps and not just the detailed steps.

[tushar5526]

Great! If you want I could open an issue and make a PR for it. It would also help me get started with the jupyter book for documentation.

[hx2A]

Thanks for the offer, but I already made that change. Have a look at the latest install instructions. If you see something that should be improved, feel free to make a PR.

Getting up to speed on jupyter book would be a good idea! Have you looked at the jupyter book documentation website? It is very helpful.

[villares]

I'm not sure if this would help, but these are my notes on trying to replicate a py5 jupyterbook environment:
https://github.com/villares/material-aulas-py5/blob/main/jupyterbook_installation_notes.md

[hx2A]

Work out why the images are broken :(

What is wrong with the images? It might be a problem I need to fix. The example images are actually created with a script in py5generator.

https://github.com/hx2A/py5generator/blob/main/py5_docs/scripts/run_example_code.py

That script doesn't work so well and I usually can't run it for all examples in one go without a random error. It's something I'll have to address in the near future.

Study how to use a makefile & pre- and post-processing scripts

There is a makefile in the py5book project that also uses a post-processing script to make some adjustments to what jupyter book does.

[villares]

I don't remember anymore what I was doing, but there is a broken image in my test page :-S
I think I hadn't figured out how to make/keep the example images.

[hx2A]

All the correct examples should be checked in.

If there are just a few broken images in the tutorials, most likely it is because you are building the website with the jupyter-book command and not the makefile. The makefile has an extra post processing script to correct a few image links that would otherwise be broken.