Component documentation

[glmnet]

Draft:

A set of guidelines to document components, I guess I can make the new schema_doc.py which will parse the md format docs to also behave like a linter enforcing the rules stated here.

[netlify]

✅ Deploy Preview for esphome-dev-docs ready!

Name	Link
🔨 Latest commit	e405cf0
🔍 Latest deploy log	https://app.netlify.com/projects/esphome-dev-docs/deploys/68600bad680068000895a97a
😎 Deploy Preview	https://deploy-preview-52--esphome-dev-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[kbx81]

Sorry it took me so long to get eyes on this, @glmnet -- thanks for working on it! We definitely need this.

I want to wait until the site migration is complete before we put this in, for two main reasons:

• I'd like to discuss a few (minor) changes to the general format...mostly just some nitpicks I have that have been bugging me for quite some time.
• I think we can streamline and better standardize a few aspects along the way. 🙂

I'll do a mock-up once the new site is live and then we can review & discuss it more...and fine-tune what you've got in this PR to match. 😄

[glmnet]

Hey buddy.
Yes since i do the docs to schema i kind of see how the docs are more or less in a structured format. But sometimes new docs drift from this quite a bit.
Unfortunately the migration to markdown is stuck, and I did this as if the migration will happen soon. But in any case this doc will also make sense for rst.

Another very important point to work on which is not in this doc is to have established how to document when there is a 'typed' prop. It's now used more often and almost every doc author has his own idea on how to document the options. And then automating anything on that is impossible.

The rest is kind of ok. May be also look later when documenting registries like filters.