Description
In #2757 we decided on moving all our docs from the rst files to the stub or python files so that static analysis tools can read and display docs (for example in editors). This works nicely, but at runtime, for modules written in C, the docstring is still just a summary and the signature lines (for example for display.set_mode: "set_mode(size=(0, 0), flags=0, depth=0, display=0, vsync=0) -> Surface Initialize a window or screen for display.") instead of the whole documentation. This means anything that uses these runtime docs (for example pydoc or the pygame discord's bot) will get little information.
Because the header generation is our extension we can change this to grab all of the text from the docs instead of just those two lines. In fact I did it, you can see the code here. While the actual code changes are not big, it highlights two problems with this change:
- this increases the size of the wheel (the artifact from manylinux x64 builds went from 87443169 to 88217844 bytes or roughly 110 kb increase per wheel)
- this means any change we do to the docs, will have an auto-generated file changed as well in the PR
The first one I don't think is too bad, since it is not too much of an increase for the benefit we are getting. But others may disagree?
The second one is annoying IMO. Keeping auto-generated files in the repo is already not that good but since it did not change often, it was not a big problem so far. On the other hand if we remove the header files from the repo then pygame cannot be built without having to generate the docs first, which isn't ideal either. Maybe we could add a macro that checks if a docstring exists and output an empty string if it doesn't? We can't check if a file is available for include only with macros, so that needs more logic too.
I'd be interested to see what people's opinion on this is. Maybe I did not think of an elegant way to handle this? Or maybe it is not worth the effort at all?