webdocs: Differentiate between type and required

[dagwieers]

SUMMARY

Now that parameters have their (non-string) type indicated in the module
docs, it becomes harder to tell which parameter is required, and what is
the type. (Mostly because both are red and positioned similarly).

Furthermore, if a non-string parameter is required, both are now
indicated subsequently.

This change makes required parameters stand out by adding asterisks to
the parameter name (in red) with an explanation at the bottom.

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

Module docs

ANSIBLE VERSION

v2.7

[dagwieers]

This change would result in:

And

[dagwieers]

cc @felixfontein

[jborean93]

IMO I like required being in the cell and not using the asterisk version, makes it a lot easier to see.

[felixfontein]

I agree that the current version looks ugly (especially when both required and the type are shown for an option), but I also agree with @jborean93 that having required written out in the cell makes it easier to see (especially for newbies who aren't used to the asterisk yet).

How about changing the styles instead? (I think we should also start using CSS classes instead of directly formatting everything inline :) )

An idea: use different colors for types and required. I'd keep required as red, but change the type to something else. Maybe blue (like the default values in the adjacent cell)? Also, if both required and type appear, the empty line between them should go away.

[dagwieers]

You have to consider that the first cell holds 4 pieces of information currently:

• parameter name -- black, bold
• required (optional) -- red
• type (optional now, but becomes mandatory at some point) -- red
• version_added (infrequent) -- darkgreen

I only noticed myself recently that someone added parameter type (with the same color) to the first cell, just like was already practice for result values.

So the usability problems are:

• None of the 3 colored values are always available (although over time we expect the parameter type to be set everywhere)
• All 3 colored values could be available for a specific parameter
• required is more important, and should stand out (preferably first)

So the easiest to make a parameter stand out is using asterisks (this is a common convention, using asterisks means a required field). This doesn't break the visual convention because it's positioned elsewhere. That's why it was done like this, to keep things consistent.

[dagwieers]

@felixfontein We should be using CSS, however we were told earlier nobody was allowed to touch the CSS styles, so we started doing it like this (eventually it being turned into CSS by @dharmabumstead).

[dagwieers]

Someone proposed adding another column, but it used to be like that and more columns is not the best use of screen-estate.

See:

• Redesign of module parameters: Improve default values and choices in module docs #36901
• Redesign of facts/return values: Improve module docs return values #36943

[bcoca]

making the name of required fields bold or red (both?) should work, as long as on top of the table we have 'X means the field is required' .. which is a pretty common pattern in docs.

[felixfontein]

@dagwieers I think I added the type name, following a suggestion by you (see #41999 and #41905).

I fully agree that having another column is not good either :)

@bcoca I wouldn't make it red, because we already use red for parameter types. But bold seems like a good idea as well (essentially what @dagwieers proposed, except that it is bold instead of having an asterisk).

Maybe we should make it both bold and add an asterisk?

[dagwieers]

Coming back to this. When a parameter is required, it does not have a default.
Which means that we could use the second column also to indicate that the parameter is required.
Only when choices exist without a default, there would be 2 things in the second column.
But maybe we can harmonize both visually ?

[dagwieers]

This is superseded by #49966.