Moved to 3.3 scope because:

• This requires changes to Libdoc's model that are a bit too big for a patch release like 3.2.2.
• Libdoc model changes are also needed by Libdoc specs: Argument name, type and default should be stored separately #3578. Better to design them together.

Well, I don't have any suggestions for styles, but would it be good idea to look few examples from IDE or how GitHub does colouring for Python type hints. Example GitHub leans to orange with white background and perhaps default values could be bluish. I would lead the argument itself to black.

Sorry if this is not applicable to this issue but it talked about formatting arguments in libdoc.

I have type hints like this within my source code:

def drag_and_drop(self: "SeleniumTestability", locator: LocatorType, target: LocatorType, html5: bool = False) -> None:

Where LocatorType previously defined as:

from selenium.webdriver.support.event_firing_webdriver import EventFiringWebElement, EventFiringWebDriver
LocatorType = Union[WebElementType, EventFiringWebElement, str]

In the docs this looks this:

locator: typing.Union[selenium.webdriver.remote.webelement.WebElement,selenium.webdriver.support.event_firing_webdriver.EventFiringWebElement, str], 
target: typing.Union[selenium.webdriver.remote.webelement.WebElement,selenium.webdriver.support.event_firing_webdriver.EventFiringWebElement, str], 
html5: bool=False

For me, having the full path to the type declaration is fine but for some this sort of presentation might be "scary" or not very readable. At least when generating html docs, it would be a bit nicer if the paths were to be shown only on tooltips and the "readable" part of the arguments would be like:

locator: Union[WebElement,EventFiringWebElement, str], 
target: Union[WebElement,EventFiringWebElement, str], 
html5: bool=False

and then, when hovering on, say, "WebElement" string, there would be tooltip (for example, with span tag and title) shown with full type information.

That definitely doesn't look good. I think it would be best if the doc just showed locator: LocatorType instead of resolving LocatorType but I don't know is implementing that possible. It probably would be better to submit a separate issue about this.

Could you @rasjani test does from __future__ import annotations help? For more details about it and why it could help see https://www.python.org/dev/peps/pep-0563/.

@pekkaklarck i dont know enough about type annotation internals to make any statements what so ever but if "test" by adding that future import to libdoc is enough, it did not have any effect at least on 3.7.7

I think just changing the splitting of arguments makes (at least in our project, but I would expect similar readability in other KWs with a lot of arguments) the arg doc much more readable. See

Was there agreement on what sort of syntax highlighting was desired and does it require libdoc model changes that are incompatible with old format?

@xylix Kerkko,

You changed this already in libdoc, right?
Could you do a PR, then Maybe @pekkaklarck could put it this min improvement to 3.2.2

Do I get it right that the enhancement by @xylix just splits arguments to multiple lines? Something like that could be done already in 3.2.2. Could possibly be done conditionally depending on argument count or the length of the whole argument spec. Another alternative would be adding max width to the argument column.

Actual syntax highlighting requires bigger changes to Libdoc model. Don't think it's safe in 3.2.2.

Generally speaking I would prefer a constant style with arguments (all formated in the same way, regardless of the number or length), because constant style makes it easier to read. From the users point of view, they may prefer current style or each argument splitted to own line and it might make better to provide a command line argument to choose which style is they prefer.

Other option could be that if library uses typing hints then all keywords arguments would be splitting to own lines. This makes easier to read the arguments and their types. And if typing hints are not present, arguments would use the current style.

@aaltat from my pov, showing typing hints is really good. Even in a long run too because that exposes a bit of python land to people and exposing same syntax is good. But there are few angles, first: How the type hints are rendered atm is IMO a bit hard to read (this is my main issue) Second: would the "Python bleed" to documentation be considered bad cuz it would give indication that core prefers python ? I don't remember seeing keyword docs made from java or remote libs having the type information shown even thou in java that most likely is very easy to implement. Which also makes me think that from POV of tester writing test data, having 2 different styles for type hints would be a bit weird ?

#3638 @pekkaklarck Do you have any input on how we should put a part of the HTML template behind a command line flag. Should we do this html base change on python side and only if flag is set?

I personally don't think this should be controlled by a command line option. This is why:

• I'm fairly certain we can come up with good heuristics when to split arguments to multiple rows and when not.
• Or if splitting arguments to own rows generally works better we can do it always.
• Which style works better varies between keywords. A single cli option doesn't take that into account.
• All configuration complicates things. In this case it would make Libdoc usage a bit harder, makes implementing this harder, requires documentation changes, etc.
• If this is configurable, it's very likely most Libdoc users don't find about this. Automatically formatting arguments better is, well, better.
• The end user is the person reading Libdoc output and they generally don't have control over the cli option.

Anyway, this topic should get its own issue where it can be discussed further. I notice @xylix already created a PR but we'd anyway need an issue for tracking purposes and discussion in the issue is preserved even if the PR would be closed and new created. Could you @xylix create the issue as well?

Made a tracking issue at #3639

Libdoc getting some kind of built-in help explaining the argument syntax would be great as well. It could get a separate issue or be implemented as part of this one.

Done