search

py-sdl / py-sdl2

Python ctypes wrapper around SDL2
Other
298 stars 50 forks source link

Documentation for SDL2_mixer/SDL2_ttf/SDL2_image extremely out of date #160

Open a-hurst opened 4 years ago

a-hurst commented 4 years ago

The official documentation sites for the mixer, ttf, and image projects are now more than a decade out of date, having last been generated in 2009 (since before SDL2 was even released). More recent documentation can be found in the actual header files (still not entirely up to date in some cases), but that's pretty arcane for people trying to figure out 1) what functions are actually available in a Python wrapper around the libraries and 2) how those functions actually work. Thus, even though this technically isn't our fault or responsibility, I feel like it might be worth it to document these libraries in the official PySDL2 docs.

To facilitate this, I partially wrote a regex script that spits out .rst files from the SDL2 headers based on function definitions and corresponding comments, which should automate a lot of the grunt work here. Still, it's going to be a bit of work.

marcusva commented 4 years ago

Do you plan to provide those efforts upstream, too? I guess that it might be a great help to them. Also, they might work on something else in parallel, so it might be worth to get in touch.

a-hurst commented 4 years ago

I mean, it's probably a good idea (there are some fairly major new features/functions added to SDL_image/SDL_ttf/SDL_mixer in the latest hg versions since the last release, so they might be looking to add online docs for those), I'd just need to figure out how to contribute stuff to the projects since they're not on GitHub.

The .rst files I'm generating are using Python format and data types though, so I'd have to backport whatever documentation I add to the C headers, stripping Python specific stuff.

marcusva commented 4 years ago

You can get in touch via https://discourse.libsdl.org/ quite easily to initiate a discussion about it and maybe file a bug with a suitable patch afterwards.