[🚀 Feature]: Consistent docstring format for python bindings (Google vs reST)

[symonk]

Feature and motivation

Right now across the code base there are docstrings in different formats. A mix of:

Google style, i.e:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

and reST style:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

I personally prefer the restructured text versions myself, but I prefer consistency across the board of anything, any preference? Ideally we should have a linter of some sort (be it a tox recipe) that enforces new docstrings are adhering to this. I think it would be useful for building out a modern docs page in future with something like mkdocs & mkdocstrings.

There might even be a tool that is smart enough to parse our files and convert each of the above to the other types, I had a look and a few tools exist but seem to be in their infancy.

Opening this ticket so we can decide exactly what type we want to apply throughout collectively. Thanks

Usage example

N/A

I see this as a phase-1 in replacing our existing python API docs (they are very old and don't look particular nice). Once we have consistent style here we can look at auto generating a modern site with mkdocs (not to be confused with selenium.dev - this is more of an API reference for python specifics)

[symonk]

also in the examples above as we add more and more types, types are inferred correctly and there is no need to document them explicitly in the docstrings.

[symonk]

https://github.com/dadadel/pyment/ is a potential option to automate the process, tho it's not something I have used before - edit: not very well maintained as of recently it would appear

[olfMombach]

I second this. Also, as a motivation, when using mixed docstring formats in IDEs like PyCharm Intellisense can get confused and I noticed it failed to read parameter specifications for methods using the deviating style.

[github-actions]

This issue is stale because it has been open 280 days with no activity. Remove stale label or comment or this will be closed in 14 days.

[titusfortner]

@symonk / @AutomatedTester did we decide what we want to do for this? Do we still have a mix of these in our repo?

[github-actions]

This issue is stale because it has been open 280 days with no activity. Remove stale label or comment or this will be closed in 14 days.

[olfMombach]

Any update on this?