Repository navigation
pyglet needs a full docstring review and cleanup #1084
Description
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.
- 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.
- Update the section in the documentation that describes our desired docstring format. This is still referencing
rststyle, 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.
- app
- canvas
- clock
- customtypes
- event
- font
- gl
- graphics
- gui
- input
- image
- lib
- math
- media
- model
- resource
- sprite
- shapes
- text
- window
Reacted by Paul
Activity
shapes.BezierCurve: fix incorrect positioning (pyglet#1084)
pushfoo commentedon Apr 14, 2024
Starting on shapes.
EDIT: finished shapes
benmoran56 commentedon Apr 15, 2024
First pass of
inputmodule is complete.input.baseshould 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 commentedon Apr 16, 2024
appandcanvasbase classes have been completed.benmoran56 commentedon Apr 23, 2024
finished
eventbenmoran56 commentedon Apr 24, 2024
Finished
sprite.pushfoo commentedon Apr 27, 2024
Starting on
libbenmoran56 commentedon May 7, 2024
Finished the
modelmodule.benmoran56 commentedon May 10, 2024
Working on
medianow.benmoran56 commentedon May 10, 2024
First pass of
mediais done.pushfoo commentedon May 14, 2024
TL;DR:
pyglet.libsis up for grabspyglet.libsto anyone who'd like to trybenmoran56 commentedon Jun 18, 2024
Working on
imageat the moment.caffeinepills commentedon Jun 18, 2024
Window was done. I will work on
graphics.shenjackyuanjie commentedon Jul 15, 2024
some cleanup in #1150
benmoran56 commentedon Jul 24, 2024
The
imagemodule has been done, and is part of this PR: #1179With that, it looks like our first pass is complete. All public modules should have been looked over and improved. Some internal modules still remain, but we can get to those as time allows.
Thanks everyone for working on this!