Require platform and entity info in manifest

[isabellaalstrom]

Context

When looking at an integration on the integrations page it's sometimes hard to gather what kind of platforms, entities and services will be available in Home Assistant. Example: Withings integration, will I be able to see the battery status of my devices? What sensors am I going to get?

Proposal

• Make it mandatory for new integrations to give this information in their manifest.
• Start documenting this in the manifest for old integrations.

Consequences

This will allow for the documentation to sync this information in the future, and also keeping the information in one place, close to the actual code, makes it easier to update when an integration updates. While allowing the frontend to show it on the integration as well.

[balloob]

How would this data be structured and used when stored in the manifest ? Is this something that we just want in teh documentation text ?

[isabellaalstrom]

Documentation text and also in the integrations panel inside ha?

[isabellaalstrom]

Another option is of course to make this a part of a template for how you are supposed to write the documentation. But then you can't easily pull in the data to integrations as well?

[NeLLyMerC]

This is something I've wanted to contribute for a few years, although I'm still not sure what will work best. To start, what if there were just a heading for "Entities" like there is now for Configuration and Services where applicable. Below it could be a table or image of each entity an integration would add and the value description/type of each. That would give the user an idea of what data an integration would give them access to. I will try to mock up an example and attach it to this thread.

[Adminiuga]

Isn't integration documentation page a better place for this kind of information?

[isabellaalstrom]

The point is for the documentation to pull in this information from the manifest. This way we get one source of truth, close to the code where changes is going to happen. It's also possible to get the integrations page in Home assistant to pull in the info from the manifest, so that it's shown on this page. Again to have one source of truth and also keeping DRY.

[isabellaalstrom]

@NeLLyMerC Yes, that is what I've thought about for showing it as well, only that the information it self comes from the manifest. Change it there and docs will update accordingly. The most important part is that the information should be there, and having it in the manifest is just an idea to keep everything together, and also allow for code reviewers that have checked the code to review this as well to keep it updated.

[pvizeli]

How would this data be structured and used when stored in the manifest ?

Make an example Isabella

[isabellaalstrom]

Basic example for a miflora device (the first thing I could think of). Added binary sensors also for more context. Something like this maybe? Or maybe there need to be a short description attached to each entity as well.

{
  "domain": "your_domain_name",
  [other manifest data],
  "entities" : 
    [
      "sensors":
        [
          "battery",
          "conductivity",
          "moisture",
          "light_intensity",
          "temperature"
        ],
      "binary_sensors":
        [...]
    ]
}

[isabellaalstrom]

Or maybe it needs to be it's own file and not be in the manifest, for brevity.

[frenck]

This architecture issue is old, stale, and possibly obsolete. Things changed a lot over the years. Additionally, we have been moving to discussions for these architectural discussions.

For that reason, I'm going to close this issue.

../Frenck