pyglet needs a full docstring review and cleanup

[benmoran56]

pyglet has gone through several documentation build tools in its life, leading to variation in the docstrings across the library. Currently we use Sphinx to build the docs, which is capable of building a variety of formats. This works for the most part but, with recent additions of type hints across the library, there is a lot of inconsistency with how the API docs are rendering.

The purpose of this ticket is to get the ball rolling on a full review and refactoring of the docstrings. This can be done in multiple parts.

• [x] Decide on a consistent style that we will use. This is currently under discussion, and includes looking at additional sphinx plugins that may improve things with regards to type hints.
• [x] Update the section in the documentation that describes our desired docstring format. This is still referencing rst style, but will potentially change. This link is here, but will need to be updated after 1. is complete: https://pyglet.readthedocs.io/en/latest/internal/doc.html
• [ ] Go through each module and update the docstrings to the new format. There are many cases where things are undocumented. It would be more time effective to skip over missing things at this time, and just focus on conversion. Many modules are still missing type hints as well, but again, it would be more time effective to leave this for later.

---

• [x] app
• [x] canvas
• [x] clock
• [x] customtypes
• [x] event
• [x] font
• [ ] gl
• [ ] graphics
• [x] gui
• [x] input
• [ ] image
• [ ] lib
• [x] math
• [x] media
• [x] model
• [x] resource
• [x] sprite
• [x] shapes
• [x] text
• [ ] window

[pushfoo]

Starting on shapes.

EDIT: finished shapes

[benmoran56]

First pass of input module is complete. input.base should now be fully type-hinted and documented, but will need to be checked if the docstrings are all building and showing. Platform specific submodules are not not type-hinted yet, but all existing docstrings have been updated. This will need to be fleshed out in a later pass.

[benmoran56]

app and canvas base classes have been completed.

[benmoran56]

finished event

[benmoran56]

Finished sprite.

[pushfoo]

Starting on lib

[benmoran56]

Finished the model module.

[benmoran56]

Working on media now.

[benmoran56]

First pass of media is done.

[pushfoo]

TL;DR: pyglet.libs is up for grabs

1. I've unexpectedly had much less free time & access to an ARM64 Mac than I'd planned
2. To make sure I don't block anyone or anything:
   • I PR'd my already-finished changes in #1108
   • I'm handing off further work on pyglet.libs to anyone who'd like to try

[matanox]

While reviewing my open issues v.s. issues here, I stumbled upon here and it struck a humble chord:

Maybe someone can obviate in PlatformEventLoop.notify's docstring whether this is a method that user code should ever call?

Do all docstrings end up on the online documentation, or is there a syntax which excludes a docstring for when it's too low level a class member?

[matanox]

Okay, read better above now, this is out of scope.