Setup PyCharm

-- 1. thanks for the pointer to the question, since I am just on the way to add a chapter about PyCharm to the docs

-- 2. To open a Python console, you must be in an existing project (just a skeleton without any modules is sufficient).
As correctly mentioned in the question, a pointer to sikulixapi.jar must be in the CLASSPATH environment variable.
It makes sense, to add it as a standard default to the global preferences (only accessible from the welcome dialog with no project open).

The problem: existing projects will not inherit this setting, when you change it globally. For those you have to add it manually to the Preferences while having the project open. Only projects created after the global Preferences change will inherit the global default settings. I did not find something like a "project settings refresh" feature.

So I setup the global preferences for the console according to the question and created a new project without any code.
Running the Python console from this project works:
from org.sikuli.script.SikulixForJython
from sikuli import *
popup("hello")

So got hello world to work but failing miserably in getting an existing sikuli script into and working

Created a blank project called "Sailing"
Made sure that Environment variables : CLASSPATH=/Applications/Sikuli/sikulixapi.jar
and Python interpretor : Jython 2.7

In Finder added an existing Sikuli Script in the "Sailing" Folder

in PyCharm
added at the start of the Sikuli Script :-
import org.sikuli.script.SikulixForJython
from sikuli import *
popup("hello world")
exit(0)

Just to make sure that it ignore the remaining code
Check interpreter and CLASSPATH again

same error

conclusion:-
I am doing something wrong - Hello World works fine - Sailing fails

Will spend more time tomorrow trying to find out where I am failing

There are 2 different scenarios, that have to be setup separately:
-- 1: running the Python console from inside an existing project
-- 2: running a script in an existing project using the Run feature backed by Configurations

for 1:
the approach in comment #1 works for using the console

for 2:
for anything else but using the console you have to use a so called Configuration:
Menu Run -> Edit Configurations

There is a set of default configurations, where you might add to the relevant configurations the environment variable CLASSPATH, so you later create configurations, that already have this preset.
... and simply saying Run for some script will auto-create a suitable Configuration, that you can edit later to meet your requirements.

Hope it helps

Not certain what my outcome is
Have created a New Project from Scratch
see below google sheet -
Tab "New Project"
then added an existing Sikuli Script
Tab "Add Existing"

https://docs.google.com/spreadsheets/d/1K87Au7BuZqYRl2iGEH6fn_b4-Ty85kxdOoJOt2o0L50/edit?usp=sharing

Can you give me comments on the results

Looks ok.

The problem:
There does not seem to be obvious rules, where and when "default" settings are inherited.
In fact, it looks like they are only "copied" once at creation time or at first use somewhere else, if at all.

So to be on the safe side, one should always check the project settings for new projects after creation and do the same for the run configurations (I always set them up manually and do not rely on the automatics - see comment #3)

There is another point not yet mentioned: code completion with regard to SikuliX features.
With the settings so far, SikuliX methods should be marked as errors (not found).
This can be repaired by adding the folder reference <sikulix-app-data>/Lib to the Project Preferences -> Project: ... -> Project Structure as additional content root

As mentioned: working on the docs for PyCharm.
Please come back with any insights, that should be doc'ed

After having made some more experiments, things turn out to be more complex, than expected.

PyCharms is principally useable in the above mentioned scenarios.

But a rather annoying caveat is the fact, that the editor (nor the console) does not support code completion with stuff residing inside of jars or Java classes - hence the complete Java API is not visible for the editor's code completion (which I remember is true for Eclipse PyDev too).

I played around a little with the IntelliJ Idea having the Python plugin: there you get at least access to the class names and method names inside the jar and Java classes when editing, but not to the parameter lists (hence still not optimal).

So for me finally IntelliJ IDEA is the better solution, since I use it for Java programming too.

Nevertheless I will complete the docs for PyCharm in this sense.