Documentation tweak ideas

[villares]

I know I have a backlog of PRs I proposed myself about documentation tweaks, but ideas come faster than I can act upon. I'd like to record here some stuff that is kind of in my mind right now before I forget.

I feel like The Modes page (https://py5coding.org/content/py5_modes.html) is hugely important for people wanting to make sense of how to use py5, it can set people for success by showing roads that fit well with their current programming skills.

• I'd like to propose you move Class mode, which is more advanced, to the end of the page.
• I think we could simplify the side note about the data folder. Isn't py5.sketch_path('data') a simpler way of finding it than importingos? Could the note be moved further down?
• Review the MacOS notes (isn't "The best option for Mac users is to use py5 through Jupyter Notebooks" a bit too strong?)
• We've been discussing somewhere else a need to have a page about the py5-run-sketch CLI command, and it should be linked on the modes page.

[vsquared]

need to have a page about the py5-run-sketch CLI command
Amen! It's under-documented, under-used, and under-appreciated in my opinion. I was lucky in that my mac Terminal utility recognized it, but I'm not sure all systems would be that fortunate; eg, my Windows 11 box has never heard of it. I'm still trying to figure out how to get 'command prompt' to recognize it. It's a powerful tool if you know how to use it. Downside: only works for Imported mode in my experience (never used Static Mode).

I only counted four modes, but maybe I missed one. All those modes are very confusing when you first see Py5.

isn't "The best option for Mac users is to use py5 through Jupyter Notebooks" a bit too strong?
I've used a lot of py5 on my mac (mostly Imported Mode) and I've never used Jupyter Notebooks, so I don't believe this is true.

[villares]

@vsquared read carefully the introductory part and you'll see that the fifth mode (py5 Processing Mode, a bridge from Java to Python) is mentioned, warning it is documented elsewhere. py5-run-sketch also works with static mode.

I think the distinction between imported and static modes is a bit overkill when using Thonny or the sketch runner, the difference is mainly having or not setup/draw, and is kind of transparent, just know that size(...) must always be on top when on static mode.

I guess the distintion makes more sense on Jupyter, because of the "py5bot" kernel that is for static sketches.

[vsquared]

What's the difference between 'py5 Processing Mode' and 'Imported Mode'? The former looks like it would be very difficult to use, just my opinion.

[GoToLoop]

After ".venv" is active on my Fish shell terminal, when I start to type in "py5", the option "py5-cmd" shows up for auto-complete.

Once I add in a hyphen "py5-", and then press TAB, all of these options appear:

py5-cmd          (command)  py5-translate-imported2module        (command)  py5-utils  (command)
py5-live-coding  (command)  py5-translate-module2imported        (command)
py5-run-sketch   (command)  py5-translate-processingpy2imported  (command)

[vsquared]

After ".venv" is active on my Fish shell terminal
How do you do that; call it first? On my mac I installed miniconda3 and venv and I always figured it was due to miniconda3 (but I could be wrong).

[GoToLoop]

I have a generic "py" .venv full of installed packages which I activate by typing in the alias "pyv":

• Bash version: alias pyv='source ~/.local/lib/py/bin/activate'
• Fish version: alias pyv 'source ~/.local/lib/py/bin/activate.fish'

BtW, I have both py5 & thonny related packages on that ".venv". Some examples:

• jpype1 1.6.0
• py5 0.10.6a0
• py5jupyter 0.2.1a0
• thonny 4.1.7
• thonny-py5mode 0.4.7a0
• trimesh 4.7.0
• shapely 2.1.1

[vsquared]

Thanks, that's what I need on my Windows box if I can ever figure out how to do it.

[GoToLoop]

When I was using Windows, I didn't have a ".venv" for it.
Instead, I've just installed all packages I needed system-wise via "pip".
Of course it's unwise installing everything globally btW.

On Linux, Python packages are installed as any other system package via the distro's package manager in place of "pip".
B/c a large portion of Linux environment depends on Python; while Windows depends on .NET framework instead.

That's why I've created a general Python ".venv" on Linux where I can have "everything" installed.
Not all Python packages are available via a distro's package manager though.
And available Python packages there, might not be the latest version either.

[vsquared]

I got the .venv installed on my Windows box and now have py5-run-sketch working. Of course now I got the old Windows error and I'm unclear if py5.jar ever got updated. May have to do it myself and I'm not a Windows guru.

[GoToLoop]

AFAIK, module venv is bundled w/ Python and doesn't require any installation!
It's invoked via: python -m venv.
Ask an AI how to use it to create a ".venv" environment.
This is the content of my "py/pyvenv.cfg" btW:

home = /usr/bin
include-system-site-packages = false
version = 3.13.5
executable = /usr/bin/python3.13
command = /usr/bin/py -m venv --upgrade ~/.local/lib/py

[vsquared]

This is what I used on Windows 11: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/ Had no idea it was already installed (not sure it was on my system).
Doesn't work on Linux because of SSL Error. Linux already knew what py5-run-sketch was, but files won't run correctly because something in py5 isn't installed correctly, which again goes back to the SSL Error. If I could ever get SSL fixed maybe all this stuff would work.