Skip to content
Use Jinja and data from Home Assistant to generate your README.md file
Python Shell Dockerfile
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.devcontainer Initial commit for Readme Aug 11, 2019
.github Initial commit Aug 11, 2019
.vscode Initial commit Aug 11, 2019
custom_components/readme Fix issue with the initial copy of the template file Aug 11, 2019
CONTRIBUTING.md Initial commit for Readme Aug 11, 2019
LICENSE Initial commit Aug 11, 2019
README.md
info.md Initial commit for Readme Aug 11, 2019

README.md

Readme

GitHub Release GitHub Activity License

hacs Project Maintenance BuyMeCoffee

Discord Community Forum

Use Jinja and data from Home Assistant to generate your README.md file

Installation

  1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
  2. If you do not have a custom_components directory (folder) there, you need to create it.
  3. In the custom_components directory (folder) create a new folder called readme.
  4. Download all the files from the custom_components/readme/ directory (folder) in this repository.
  5. Place the files you downloaded in the new directory (folder) you created.
  6. Restart Home Assistant
  7. Choose:
    • Add readme: to your HA configuration.
    • In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "Generate readme"

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

Example configuration.yaml

readme:

Configuration options

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.)

Warnings!

This integration will replace your files!:

  • README.md
  • ui-lovelace.yaml (if you enable convert_lovelace)

Usage

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.

Usable variables

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_components

The information about custom components are fetched from the integrations manifest.json file, the folowing keys are aviable:

  • domain
  • name
  • documentation
  • codeowner

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 -%}

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._

Contributions are welcome!

If you want to contribute to this please read the Contribution guidelines


You can’t perform that action at this time.