Separate action field YAML examples

[davet2001]

Proposed change

When the user selects the Actions page in Developer tools, the YAML examples should be separated, rather than displayed as all one word. For more information see #27217.

Before:

After:

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (thank you!)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

One thing I'm not so sure about is the added whitespace before and after the text in the <td>. The automatic (prettier) formatting added whitespace which then showed up in the output. I fixed this by adding a <!-- prettier-ignore --> statement but I'm not sure this was fully necessary, as my build showed this problem whitespace on the output both before and after the change.

• This PR fixes or closes issue: fixes Actions yaml examples are not comma separated #27217
• This PR is related to issue or discussion:
• Link to documentation pull request:

Checklist

• The code change is tested and works locally.
• There is no commented out code in this PR.
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

[frenck]

I think comma separation should be avoided; should we make a list instead?

[davet2001]

As in one above the other in a veritical list?

[davet2001]

With <ul><li>xxx</li>...</ul> I get this:

Feels like the <ul> indentation is a bit too much.

[karwosts]

Note that when the example is a complex object, in other cases (excepting this service listed which has a broken example with [object Object]), we most often display it as json:

This will be correct if user copies and pastes it into his yaml.

Using the same approach, should we display it as json array like ["mean", "sum"] ?

Then user may copy/paste example into his code.

Displaying it as a comma separated string "mean, sum" will be an error if user pastes into code.
Displaying it as a list will not be copyable either.

[davet2001]

My feeling is that an example should be exactly one example that can be copied and pasted in it's entirety and will work.

For that reason, I don't think even the ability to have a list of examples in the services.yaml makes sense. Sometimes as @karwosts says, the example could be a json dict object that is intended to be pasted in its entirety. Other times it could be an array, and then we want the user to not paste the whole array, but just pick one of them? What about a array of dicts? Or a dict containing arrays? Could be confusing. If we want to list several possible options, I think that should be in the description.

So perhaps the solution is to remove all instances where there is more than one example in services.yaml and update the validator to enforce it.

I don't have a strong view on this, so happy to go with what others think, but we shouldn't display multiple examples without any delimiter.

[davet2001]

See comment here: #27217 (comment)

Now I see that the examples are not discrete examples, but rather a list that the user could enter in it's entirety, where they are requesting all items in that list.

[karwosts]

I have seen some service authors confused from time to time and write things like "foo OR bar" in their example, which should probably be discouraged when discovered, though I don't know how you can check for that 😅

[davet2001]

So in that case, what about if we JSON.stringify() everything? (That also fixes the [object Object] problem)...

[davet2001]

I have seen some service authors confused from time to time and write things like "foo OR bar" in their example, which should probably be discouraged when discovered, though I don't know how you can check for that 😅

Could one of the pytests be to put the services.yaml examples into the validator for that service?

[MindFreeze]

Mixing JSON with YAML seems confusing. I propose just YAML formatting complex objects like this, where dump is imported from "js-yaml"

Suggested change

	${this.hass.localize(
	`component.${domain}.services.${serviceName}.fields.${field.key}.example`
	) || field.example}
	) || JSON.stringify(field.example)}
	${this.hass.localize(
	`component.${domain}.services.${serviceName}.fields.${field.key}.example`
	) ||
	(typeof field.example === "object"
	? html`<pre>${dump(field.example)}</pre>`
	: field.example)}

[davet2001]

@MindFreeze agreed, although in some instances json is way more helpful (e.g. if feeding the data into the REST API - which is what I was doing when I stumbled across this issue).

Would having two example columns (one for JSON, one for yaml) be out of the question?

I noticed the Microsoft started doing similar a while ago where they have a help page with API examples in multiple languages.

[bramkragten]

I don't think this page is meant for using/documenting the REST API, we generally use YAML for everything, and that is what we should display here. I would not add yet another column.

[MindFreeze]

Please change the formatting to YAML as suggested

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.