Generate reST/ref docs from python or stub files, move time and cursors docs

[zoldalma999]

Related to #2757

This PR implements autodoc style documentation generation. This allows us to have documentation in python files or (if the module is implemented in C) in stub files. It uses autoapi because stub files are not runnable python files thus we cannot use autodoc. These changes are under the commit Generate reST/ref docs from python or stub files.

This PR also ports two modules (time which is a C based module and cursors which is a python based module) as reference. Following modules can be easily ported based on these by anyone.

The generated docs should look almost the same. The only changes are to signatures and summary lines. Signatures will now use the stubs as their source, which means that argument names and default values should be more accurate. But this also means that we cannot just write anything there. Because of this return values are now types (or just "..." if it is too complex) not some descriptive names. Summary lines also change a bit to conform to the convention of having a full sentence as the first line of docstrings (this of course can be reverted if others are against it).

Future work related to this:

• Move all the of the ref/ content either to python/stub files or to guides.
• Switch to full autogeneration, and delete the ref/ folder.
• Add accurate typing info to the documentation, taken from stubs.
• (Possibly) Generate better header files (include the whole docstring not just the summary line and signatures).
• Write a guide (or extend an existing one) on how to contribute docs (conventions and standards, how to contribute, maybe small guide to rst and useful links).
• Remove version[added|changed|deprecated]old and let version[added|changed|deprecated] figure out if it needs to say pygame or pygame-ce.

[ankith26]

Overall, this is a really good idea and should make things better, thanks a lot for getting work started on this!

I have left a couple of thoughts/reviews for your consideration

[Starbuck5]

I'm curious about the flexibility of this system. Can we have content in the rst docs that surrounds content pulled from stubs? I feel like it would to nice to have method docs pulled in from stubs into a manually set up page with examples and other things.

Why are the cursor docstrings in the Python code for Python modules? All modules have stubs that can be used.

[zoldalma999]

I'm curious about the flexibility of this system. Can we have content in the rst docs that surrounds content pulled from stubs? I feel like it would to nice to have method docs pulled in from stubs into a manually set up page with examples and other things.

I don't see why we wouldn't have examples and "other things" already in the docs but yes we can, though it is a bit more verbose. Say you wanted to add some extra info under pygame.time.delay

.. autopgmodule:: pygame.time

.. autopgfunction:: get_ticks

.. autopgfunction:: wait

.. autopgfunction:: delay
   
   This sentence will be right under delay's docs (note the extra newline above).

.. autopgfunction:: set_timer

.. autopgclass:: Clock
   :members:

Why are the cursor docstrings in the Python code for Python modules? All modules have stubs that can be used.

Because I wanted those to be proper docstrings that get picked up by python. If we put them in the stub files things like the builtin help function, pydoc or object.__doc__ would not work (but Ankith asked me the same question, at least a note somewhere of how this works could be nice?).

[Starbuck5]

This is a hard PR to approve because it changes our approach to documentation significantly.

But this should lead to a really nice improvement in user experience.

I like how you did it as two example modules at first, minimizing the changes. I like your writeup. I like that you are not a drive by contributor and if this breaks I can ping you about it 😄

So with that in mind, thank you for the PR-- let's try this out!