RFC: Auto-Generate the Home Assistant Docs

[jonnylangefeld]

The problem

I understand this is a big task, but hear me out:

The current Home Assistant docs are helpful, but not ideal.

For Developers

• Developers have to write the doc strings and the schema in two different places. As an example let's take the service light.turn_on. All available fields are visible to a user in the official home-assistant.io docs pages. These fields are ultimately written by a developer in the home-assistant/home-assistant.io repo. And then the actual schema is ultimately defined in home-assistant/core (link leads to LIGHT_TURN_ON_SCHEMA). That's not ideal as sometimes updates to the schema don't always make it to the markdown files.

For Users

• It's not always clear what fields a child resource contains. For instance the docs for trigger have many examples but nowhere can a user see what fields a trigger allows. But this data is available in the code via the voluptuous schema. For instance this is the voluptuous schema for the sun component.
• Sometimes the docs and the implemented schema diverge. For instance the light template schema doesn't contain a set_white_value anymore (because it was removed in 2022.9, but it is still present in the docs because it hasn't been removed there after the deprecation.

The Solution

This is a proposal open for discussion. All Schemas are implemented using alecthomas/voluptuous. For instance this is the base schema for the automation.yaml. Voluptuous schemas also allow for a docstring via the description field as implemented by @balloob himself. Currently home-assistant/core doesn't make use of that description field.

We should extract the docstrings from the markdown files and add them via the description attribute to the voluptuous schemas.

Furthermore we should then use the voluptuous schema structures and serialize them. My suggestion for serialization is a .proto file because from there we can generate any other format like markdown, html or openapi specs.

Proof of Concept

To validate this concept I have created a PR against home-assistant-libs/voluptuous-serialize, which is a repo created by @balloob that is already used in home-assistant/core today, however only to a minimal extend and it doesn't support complex data types such as dictionaries and lists. So that would need to be added.
Check out my PR here: home-assistant-libs/voluptuous-serialize#65

ToDo's

A simplified list of what I think would need to get done to make this happen:

• update home-assistant-libs/voluptuous-serialize to understand all complex data types and all voluptuous options
• transfer doc strings which currently live in distributed markdowns into the voluptuous schemas in code.
• add a generator to the home-assistant/core CI to translate the voluptuous schema to .proto files and the .proto files to nicely looking docs pages, for instance via pseudomuto/protoc-gen-doc.

What do you all think about that?

What version of Home Assistant Core has the issue?

2022.12.1

[home-assistant]

Hey there @home-assistant/core, mind taking a look at this issue as it has been labeled with an integration (light) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of light can trigger bot actions by commenting:

• @home-assistant close Closes the issue.
• @home-assistant rename Awesome new title Change the title of the issue.
• @home-assistant reopen Reopen the issue.
• @home-assistant unassign light Removes the current integration label and assignees on the issue, add the integration domain after the command.

_{^{(message by CodeOwnersMention)}}

---

light documentation
light source
_{^{(message by IssueLinks)}}

[frenck]

IMHO the most viable way of bringing in something from the existing codebase to the docs, would be all services.yaml files (which I have experimented with and is easy to do, styling is the biggest issue) & manifests files (the latter is already partly synced @ release).

Vol schemas are used for lots of things; most do not even translate well to docs at all (or are dynamic of nature). I don't see how that ever could be used in a sane way to get fully automated docs. It really becomes painful if you want to diverge deliberately from generated code.

That said, in the end, generated docs are a developer approach. But in the end, documentation is an end-user approach. They don't translate well.

PS: I'm not sure if this belongs in our issue tracker at all; probably more of an architectural discussion.

[jonnylangefeld]

@frenck Wow that was a fast response!

That said, in the end, generated docs are a developer approach. But in the end, documentation is an end-user approach. They don't translate well.

Does that mean you're not in favor of auto-generate docs? Or in favor of partially auto-generated docs?

I would have argued that developers are also users in a sense. They are users of the code. And usually they work on code that someone else previously worked on. So I would say it's also very useful to developers if they find a docstring right in the code. So I find it very useful to re-use that same doc string for a field in the end-user documentation. Especially because the developer would need to think twice otherwise. Once for the documentation in the code itself and once for the user doc.

But I understand that it's a big effort and the cost/gain relation might be off...

[frenck]

Does that mean you're not in favor of auto-generate docs?

I think it can be a tool, especially for validation, but absolutely not a solution.

I would have argued that developers are also users in a sense.

That is what developers say... Yet, they are, in general, the worst documenters and more often disconnected from the end-user in providing understandable and good documentation.

This is not just in missing docs, or things like that. Just the language used by us developers and things we find normal... while a user has huge question marks above their head trying to read a sentence we wrote 😓

So I would say it's also very useful to developers if they find a docstring right in the code.

Sure! But the level is different. Docstrings are already here and enforced in the HA codebase. API document is also there (which is a good example of good developer documentation that is completely useless to end-users).

The biggest source of YAML we have is our service calls. For those, we actually have YAML files of their definitions, which include descriptions, defaults, and even examples and selector information. As a matter of fact, the UI of Home Assistant is based on those.

Pulling those in will provide most of the general day-to-day use into our docs already. Not just for YAML, but also for how they would be represented in the UI.

What is left are integrations that have YAML configuration for the integration itself (integration config or platform configuration). Both of those are dying and phased out. We stopped accepting changes (or addition) to YAML for integrations that connect to devices and services about 3 years ago.

So, for integrations/platform configuration, it is mostly complete removal from the docs (no other changes).

The gaps here are triggers, conditions, actions & automation/scripts. Those are fairly consistent. They are very, very low in changes and barely get breaking changes because of their importance in HA. The schema is small; the documentation, however, needs a lot of extensive explanation (of which we do not have enough tbh). I'm not convinced any automated generated thing will solve anything for these concerns, simply because of the complexity of usage.

Lastly, the frontend/dashboard stuff. All of that isn't defined in Python.

---

TL;DR: IMHO, what our docs need most; is more guidance and examples, with more focus on the UI that people use (instead of YAML) and, above all: End-user, non-developer, human language that even my dad would understand.

😉

[issue-triage-workflows]

There hasn't been any activity on this issue recently. Due to the high number of incoming GitHub notifications, we have to clean some of the old issues, as many of them have already been resolved with the latest updates.
Please make sure to update to the latest Home Assistant version and check if that solves the issue. Let us know if that works for you by adding a comment 👍
This issue has now been marked as stale and will be closed if no further activity occurs. Thank you for your contributions.