Do we need to add docstrings to the pyi files?

[Starbuck5]

trafficstars

I feel like I used to see docstrings in my dev environment (VS code), but I don't see them now.

All I see right now is the type information, for example:

If I go into event.pyi as a test and replace the ... with a docstring, it shows up:

def event_name(type: int, /) -> str: ...
def set_blocked(type: Optional[_EventTypes], /) -> None:
    """blocked blocked blocked blocked..."""
def set_allowed(type: Optional[_EventTypes], /) -> None: ...
def get_blocked(type: _EventTypes, /) -> bool: ...
def set_grab(grab: bool, /) -> None: ...

If I hover over pygame.event.set_blocked I now see this very insightful information:

This seems like a big win if we can solve this in a nice manner.

[ankith26]

I remember discussing this in previous issues (I'm not able to find any links RN)

Anyways, my take was that we can either

1. Make or use a tool that can copy the docs from code into the stubs
2. Update the tool being used by VS code to somehow pick up the docs from the implementation?

Basically, I don't want it to be a manually updated thing that adds developer burden

[Starbuck5]

There are lots of possibilities here.

• Our runtime docstrings are generated from the docs sl/sg attribute
• Docstrings could be more detailed by taking in information from the rest of the docs
• Do most editors render docstrings as markdown?
• We can use markdown instead of reST in our docs, should we?
• Different function signatures could be annotated differently to explain the args that are actually being used.
• We could generate docs from stubs and have the stubs be the universal source of truth, or vice versa. We could put a universal source of truth for stubs and docs in the code and have everything be generated off that.
• We could try to unify the method overloading in the stubs with the method overloading expressed in the documentation.
• Manual might not be so bad, the stubs are already manually written.

[ankith26]

We could generate docs from stubs and have the stubs be the universal source of truth, or vice versa. We could put a universal source of truth for stubs and docs in the code and have everything be generated off that.

Hmmm. I think I like the idea of not having separate .rst files for docs. We could have all docs as docstrings in the stubs, and generate docs from this. This will be a lot of manual porting/labour work, but it may pay well in the long run

[Starbuck5]

@zoldalma999 Now that the initial PR is merged I'd like to see this continue to move forward. I remember you said you had a branch with a lot of this already done.

[zoldalma999]

For anyone who wants to help progress with this, here is how to copy portions of docs to the stub files. I'll use pygame.key.get_focused as an example.

1. Open up the rst file for your chosen module. It will be in /docs/reST/ref/. In this example mine will be key.rst.
2. Find the function that you want to copy over. Mine will be starting on line 241: https://github.com/pygame-community/pygame-ce/blob/80fe4cb9f89aef96f586f68d269687572e7843f6/docs/reST/ref/key.rst?plain=1#L241-L250
3. Open up the module's stub file. This will be under buildconfig/stubs/pygame/. You should be able to find the function you are copying fairly easily.
4. Copy over the the summary line (the text after | :sl:) as the first line of the docstring in the stub file. Then capitalize the first word, and put a period at the end. In my case, this will look like this:

def get_focused() -> bool:
    """True if the display is receiving keyboard input from the system."""

5. Then take the rest of the docs (from the first line that does not start with | to either the next function or a comment like .. ## pygame.{module}.{name} ##) and copy it into the docstring of your function. Make sure that the indentation is right (rst uses 3 spaces for indentation, while python files use 4. A simple way to fix this in vscode is to select the text, press shift+tab and then press tab.) and that there is no trailing whitespace.
6. Delete all the content you just copied over and replace the .. function:: {name} directive with .. autopgfunction:: {name}. After these changes your rst file should look like this:

[...]
.. autopgfunction:: get_focused
[...]

and your pyi file:

[...]
def get_focused() -> bool:
    """True if the display is receiving keyboard input from the system.

    Returns ``True`` when the display window has keyboard focus from the
    system. If the display needs to ensure it does not lose keyboard focus, it
    can use :func:`pygame.event.set_grab()` to grab all input.
    """

[...]

7. Finally, from the root of the project run python dev.py docs --full to generate the documentation and python -m docs to open the generated docs. Navigate to your function and check if it looks alright.

If you are copying over something different (like a method, property or attribute), this should look the same, except for step 6, in which you would not write .. autopgfunction:: {name} but the correct type instead (so in case of a method, it would be .. autopgmethod:: {name}. If you have any questions, feel free to @ me on the pygame discord server in the contributing channel, or comment here.

Here are some of the easy modules to do. Feel free to do more than one function per PR.

• [ ] mouse
• [ ] key
• [ ] mixer
• [ ] event
• [ ] gfxdraw
• [ ] scrap
• [ ] pixelcopy
• [ ] Color
• [ ] mask