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)
Feature and motivation
Right now across the code base there are docstrings in different formats. A mix of:
Googlestyle, i.e:and
reSTstyle: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)