Use Jinja and data from Home Assistant to generate your README.md file
- Using the tool of choice open the directory (folder) for your HA configuration (where you find
configuration.yaml). - If you do not have a
custom_componentsdirectory (folder) there, you need to create it. - In the
custom_componentsdirectory (folder) create a new folder calledreadme. - Download all the files from the
custom_components/readme/directory (folder) in this repository. - Place the files you downloaded in the new directory (folder) you created.
- 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 Jijna 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 |
The information about custom integrations are fetched from the integrations manifest.json file, the folowing keys are available:
domainnamedocumentationcodeownersversion
The information about integrations tracked with HACS are fetched from the storage hacs files, the folowing keys are available:
categorynamedocumentationauthorsdescription
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 -%} 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 %} 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 only use this integration the output of that will be:
### [Generate readme](https://github.com/custom-components/readme) _Generates this awesome readme file._ If you want to contribute to this please read the Contribution guidelines