[Bug] Platform and Sensors further feedback (Using debug: as guide)

[masterofnonemx]

What happened?

This a follow up to these closed bug reports:
#383
#419

After testing the fix in #383 the following issues come to my attention

• When adding a platform component (e.g. Debug Sensor/Text Sensor) the wizard card shows the description of one of the dependant sensor as shown in the following screenshot. This is confusing because leads the user to think that it's adding the sensor instead its base platform.

• When finished adding the platform component, all sensors are marked as optional and hidden behind the Show advanced settings. At first I thought that I had added the wrong component until I realized where they were. It seems as if the just added platform had no configuration options. Could they be marked as "enable-by-default" to avoid this confusion in the future? As in the previous comment, the component form shows the description of one of the dependant sensors instead a more generic description related to the platform.

• I think it is a little weird that one have to put a Name in the sensor so that it is added to the YAML, but this is the way implemented in other components with multiple sensors. I understand that the aim could have been sensor discoverability, but this is defeated by hiding all the sensors behind advanced options as mentioned earlier. Another option could be, in multisensor platforms, to add an "Enable Option" per sensor instead of adding then when a name is set; a simple switch could be enough.
• In [Bug] Adding sensor.debug / text_sensor.debug lands a no-op YAML (all sub-sensors optional) #419 it is also mentioned the posibility of listing in the Add component wizard all components belonging to a platform (Maybe Group By Platform?) vs only the platform component. This way the end user could search and add the sensor that he is interested in directly, vs having to add the platform and after that, enabling the desired sensor. I think this idea is worth exploring.

#419 has a good summary of all the points I've mentioned here; it should be read for a better technical reference. As always, I understand that this points are all a design decision, I leave it in your hands guys.

Dashboard version

beta24

How did you install it?

Wheel from a GitHub release

Where is it running?

Local — Linux

Relevant logs / errors

Anything else?

No response

[marcelveldt]

thanks for the follow-up.

point 1 (wrong description on the sensor.debug / text_sensor.debug cards) is real and traces upstream to esphome/esphome-docs. in script/schema_doc.py, md_get_paragraph skips titles but then accepts the first ### Configuration variables bullet as the paragraph when there's no prose between ## <Platform> and the configuration-variables heading — that bullet ends up baked into the schema bundle as the platform component's docs field, which we render as the card / form description.

upstream fix is small, in md_get_paragraph — treat a leading list marker like a code block and return None:

     if lines[index].startswith("```"):  # got a code block, return None
         return index, None
+    stripped = lines[index].lstrip()
+    if stripped.startswith(("- ", "* ", "+ ")) or re.match(r"^\d+\.\s", stripped):
+        return index, None

will file that on the docs repo separately. in the meantime the next backend release ships a workaround in script/sync_components.py (_repair_field_bullet_descriptions) that detects the bullet shape and substitutes the bare-stem umbrella entry's description, so both cards now show the proper "The debug component can be used to debug problems with ESPHome..." prose. cheap to rip out once upstream lands.

points 2 + 3 (every sub-sensor hidden behind "show advanced", "type a name to enable") are the same root cause as #419, but you're the second user hitting it in practice so worth a fresh look. needs a backend classify change for sub-sensor menus and a frontend enable-toggle. tracking separately from this fix.

point 4 (group-by-platform in the wizard) is a frontend feature request — out of scope here.

cc @jesserockz on the schema_doc.py bit — figured you'd want eyes on it.