Differences in parameter docs

[eschan145]

In many Python projects (such as pyglet), parameters are documented like this.

:Parameters:
    ``minimum`` : ``int``
        Minimum value for random number.
    ``maximum`` : ``int``
        Maximum value for random number.

Arcade is different. It lists each parameter with the prefix :param, and it is overly repetitive. An indented parameter list looks much neater and more smoother. Additionally it looks more consistent on how the docs actually turn out (the word "Parameters" is right above the parameter list in the API docs). Is there a specific reason why Arcade's documentation is set like this? I'd be happy to fill out PRs to fix this.

[pushfoo]

tl;dr Maybe, but not just because it looks better in the editor

The current style is the well-supported default of both sphinx & IDEs. However, it's worth investigating whether the advantages it or other styles could bring to our HTML rendering are worth the work of switching.

The current reStructuredText style

The current style makes the project more accessible to beginners:

1. Sphinx supports it out of the box with no plugins
2. IDEs support it out of the box with no plugins or configuration changes

The exception to this is VS Code's hover tooltip, which doesn't seem to like anything but markdown.

The proposed Google style

The Google style pyglet uses has the following downsides:

1. pyglet uses the napoleon extension, which may slow down our builds since it converts to reST format internally
2. You have to manually switch on Google style support in PyCharm, and other IDEs may or may not have support for it

When/why would we switch?

There are other tickets related to doc formatting (#1239 , #1259) which may overlap with this one, and we should investigate how docstring style affects them. If there are considerable benefits, then maybe we'll switch. However, better appearance in the editor alone likely isn't worth the massive undertaking of switching our docstring format.

[einarf]

I'm personally more a fan of google style docstrings because they are more human readable while RST is easier to parse. I think the only reason we're using the traditional RST style is because PyCharm is using this by default.

Converting between these two formats are not too difficult. It can be automated with a python script. Still, it's not a small amount of work.

This is something we'll have to discuss on discord. I don't know how people feel about changing the format. We're only talking about the parameter lists here.

[einarf]

From discusson in Discord it looks like the consensus is "I don't really care what docstring format we use". Pyglet is using numpy style docstrings. We are using plain rst ones.

I suggest we just go with google style since this is the most human readable. The html output will more or less be identical.

Suggesting the following plan:

• Make a script in the util directory for automating the conversion
• Recuse through all modules and members in arcade
• Locate classes, methods and functions
• Inspect the actual arguments of the function and group them in args and kwards
• Parse the current docstring parameters
• Output google style docstring with separate args and kwargs sectons

Using Args, Keyword Args, Returns and Raises should be enough.

The supported sections are here : https://sphinxcontrib-napoleon.readthedocs.io/en/latest/#docstring-sections

[pushfoo]

I have one major concern which I don't think I emphasized clearly enough on the discord: we need to provide clear doc on how to enable this in PyCharm, or ideally, automate this or include it in a boilerplate repo.

[Cleptomania]

I missed the conversation about this on discord, but +1 for the google docstrings(though I don't have a strong opinion, just slightly prefer it), and the approach @einarf laid out looks like it would make the most sense, covering all of this manually is probably not feasible.

@pushfoo Is this a common problem among PyCharm users? We would be far from the only library using this style of docstrings. We already have installation/setup instructions for PyCharm, so I would think any instruction about it would probably fit best in there.

[pushfoo]

I need to fix the TiledMap docs if/before we run a conversion script. They're half-way between the formats and already causing problems in their current state, and will continue to do so.

Is this a common problem among PyCharm users?

I'm not sure, but arcade is still a beginner-oriented library, so lower barrier to entry is a good thing imo.

We already have installation/setup instructions for PyCharm

Not up to date ones, according to #1321. It's easier to have a commented project boilerplate or generator than it is to have users step through PyCharm setup instructions we have to maintain.

[einarf]

We specify google style docstrings is the standard now. Pyglet are also moving over to these

[pushfoo]

Pyglet's Google-style minus types: https://pyglet.readthedocs.io/en/latest/internal/doc.html#docstring-rules