Use Jinja and data from Home Assistant to generate your README.md file with the list of all your installed add-ons and custom components
- Download it with HACS
- Restart Home Assistant
- Choose:
- Add
readme:to your HA configuration. - In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Generate readme"
- Add
Using your HA configuration directory (folder) as a starting point you should now also have this:
custom_components/readme/.translations/en.json
custom_components/readme/__init__.py
custom_components/readme/config_flow.py
custom_components/readme/const.py
custom_components/readme/default.j2
custom_components/readme/manifest.json
custom_components/readme/services.yaml
readme:This integration will replace your files!:
- README.md
- ui-lovelace.yaml (if you enable
convert_lovelace)
| Key | Type | Required | Description |
|---|---|---|---|
convert_lovelace |
boolean |
False |
Generate a ui-lovelace.yaml file (only usefull if you use the UI to edit lovelace and want to share that in a yaml format.) |
In the root of your configuration directory (folder) you will get a new directory (folder) called "templates" in that directory (folder) there will be a file called "README.j2" this is where you change the template that will be used for generation of the README.md file.
When you are happy with how the template look, run the service readme.generate in Home Assistant, this will generate the README.md file, and the ui-lovelace.yaml file if you enabled that.
In addition to all Jinja magic you can do, there is also some additional variables you can use in the templates.
| Variable | Description |
|---|---|
states |
This is the same as with the rest of Home Assistant. |
custom_components |
Gives you a list of information about your custom_integrations |
hacs_components |
Gives you a list of information about HACS installed integrations, plugins, and themes |
addons |
List of installed Home Assistant Add-ons |
The information about custom integrations are fetched from the integrations manifest.json file, the folowing keys are available:
domainnamedocumentationcodeownersversion
Example usage of the custom_components variable:
{%- set custom_component_descriptions = {"readme": "Generates this awesome readme file."} -%}
{% for integration in custom_components %}
### [{{integration.name}}]({{integration.documentation}})
{% if integration.domain in custom_component_descriptions %}
_{{custom_component_descriptions[integration.domain]}}_
{% endif -%}
{% endfor -%}
The information about integrations tracked with HACS are fetched from the storage hacs files, the folowing keys are available:
categorynamedocumentationauthorsdescription
Example usage of the hacs_components variable:
### Integrations
{%- for component in hacs_components | selectattr('category', 'equalto', 'integration') | sort(attribute='name') %}
- [{{component.name}}]({{component.documentation}})
{%- endfor %}
### Lovelace
{%- for component in hacs_components | selectattr('category', 'equalto', 'plugin') | sort(attribute='name') %}
- [{{component.name}}]({{component.documentation}})
{%- endfor %}
### Themes
{%- for component in hacs_components | selectattr('category', 'equalto', 'theme') | sort(attribute='name') %}
- [{{component.name}}]({{component.documentation}})
{%- endfor %}
The following keys are available:
nameslugdescriptionstateversionversion_latestupdate_availablerepository
Example usage:
## Add-ons
{%- for addon in addons | sort(attribute='name') %}
- {{addon.name}} ({{addon.version}}) - {{addon.description}}
{%- endfor %}
Example usage for documenting Alexa smart home utterances
{%- set alexa_configuration =
{
"domains": ["light", "camera", "vacuum", "fan"],
"entities": {
"included": ["climate.downstairs", "input_boolean.guest_mode", "input_boolean.assistant_notifications", "input_boolean.andrea_morning", "cover.garage_door"],
"excluded": ["light.kitchen_light_1", "light.kitchen_light_2", "light.cabinet_split", "light.cabinet_large", "light.test_sensor_led", "camera.doorbell"]
}
}
-%}
{%- macro sentence_case(text) -%}
{{ text[0]|upper}}{{text[1:] }}
{%- endmacro -%}
{% set data = namespace(domains=[]) %}
{%- for state in states %}
{%- if (state.entity_id in alexa_configuration.entities.included) or (state.entity_id not in alexa_configuration.entities.included and state.domain in alexa_configuration.domains) %}
{%- if state.domain not in data.domains %}
{%- set data.domains = data.domains + [state.domain] %}
{%- endif %}
{%- endif %}
{%- endfor %}
{%- for domain in data.domains %}
### {{ sentence_case(domain) }}
{%- if domain == 'climate' %}
Control a thermostat temperature, run mode, etc...
Climate Mode | Accepted words
-- | --
AUTO | "auto", "automatic"
COOL | "cool", "cooling"
HEAT | "heat", "heating"
ECO | "eco", "economical"
OFF | "off"
**What you say:**
_"Alexa, set thermostat to 70."_
_"Alexa, set the AC to 70."_
_"Alexa, make it warmer in here."_
_"Alexa, make it cooler in here."_
_"Alexa, set `DEVICE NAME` to `CLIMATE MODE`."_
_"Alexa, turn on the `CLIMATE MODE`."_
_"Alexa, turn off the `DEVICE NAME`."_
{% endif %}
**Device Names:**
{%- for state in states[domain] %}
{%- if (state.entity_id in alexa_configuration.entities.included) or (state.entity_id not in alexa_configuration.entities.included and state.domain in alexa_configuration.domains) %}
{%- if state.entity_id not in alexa_configuration.entities.excluded %}
- {{state.name}}
{%- endif %}
{%- endif %}
{%- endfor %}
{%- endfor %}
If you want to contribute to this please read the Contribution guidelines
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent