Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

zoldalma999
Copy link
Member

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.

@zoldalma999 zoldalma999 requested a review from a team as a code owner October 22, 2024 08:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant