Move Window, display and system docs to stubs

[zoldalma999]

Some progress on #2757

[ankith26]

LGTM, thanks a lot for working on this! 🎉

Did a side by side comparison of the generated docs and the current docs on pyga.me, and found everything matching up nicely.

[Starbuck5]

Doing a side by side is a good idea for reviewing, I did so myself as well.

In Window I see a few issues. The new generation shows most (but not all?) properties as methods.

It's Window.position, not Window.position().

Another thing about position is that previously it mentioned that it could be the CENTERED or UNDEFINED constants.

One other thing I noticed is that display.update doesn't show that it takes a list of rectangles in its signatures list:

Actually on more investigation it is the website that's out of date there, I told it to unpause its scheduled docs uploads.

[Starbuck5]

There also is a merge conflict due to #3295

[bilhox]

Before merging this PR, I'm more concerned about how the docstring is displayed by VSC:

The format doesn't really match, I thought maybe I need to install an extension for rst docstring, but then I saw numpy documentation :

[zoldalma999]

The new generation shows most (but not all?) properties as methods.

Good catch, should be fixed now!

Another thing about position is that previously it mentioned that it could be the CENTERED or UNDEFINED constants.

That is because we could write anything there before. Right now return types are grabbed from the stubs. I added it to its description tho (which is where it belongs anyway in my opinion).

One other thing I noticed is that display.update doesn't show that it takes a list of rectangles in its signatures list

Again, stubs. The rectangle argument is typed so that it can be either one rectangle or a list of them. Could add another overload for it if you want me to (or change rectangle to rectangles)

Before merging this PR, I'm more concerned about how the docstring is displayed by VSC

They use their own style, which vsc (or rather, pylance) can render properly. RST is still a preview feature, and needs to be enabled manually.

[Starbuck5]

Again, stubs. The rectangle argument is typed so that it can be either one rectangle or a list of them. Could add another overload for it if you want me to (or change rectangle to rectangles)

Probably another overload would do it. Right now the docs it generates are misleading because it just says "rectangle".

[Starbuck5]

I still see weirdness with properties in Window.

All 4 of these are in Window.c getsets but half of them are seen one way and half of them are seen as functions.

[zoldalma999]

I still see weirdness with properties in Window.

Maybe try doing a full generation? It does work for me.

Probably another overload would do it. Right now the docs it generates are misleading because it just says "rectangle".

Done!

I also fixed the warning that display.message_box threw about the window parameter. Now it should always link to the correct one.

Some things I noticed that could be worked on:

• There's undocumented stuff related to window: pygame.window.get_grabbed_window and Window.relative_mouse
• pygame.system.get_power_state has an experimental notice that it had for a while now. I think it can be removed at this point?
• Maybe display.Info could be turned into a proper class with an init function, like we did with the rest of the classes. Also, add docstring for each attribute copied from the display.Info function.
• Deprecate icontitle in pygame.display.set_caption - it does nothing and in pygame 3 change get_caption to only return a single string
• display.get_num_displays references SDL 1 behavior

[Starbuck5]

OK, looks good. Thanks!

My only suggestion is that it some of the code in documenters.py looks like it could use a comment. Like why if the the thing is a property does the arg string need to be changed? I could see that being confusing to the next person to edit that code.

[zoldalma999]

I'll merge this for now, and will add some comments to the code in my next PR.