Skip to content

Commit 09d4863

Browse files
DigiLiveDigiLive
committed
Add wiki documents
1 parent 2fd1be9 commit 09d4863

23 files changed

+1132
-4
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# .github/workflows/deploy.yml
2+
name: Deploy Documentation
3+
4+
on:
5+
push:
6+
branches:
7+
- main
8+
paths:
9+
- 'docs/**'
10+
- 'mkdocs.yml'
11+
12+
permissions:
13+
contents: write
14+
15+
jobs:
16+
deploy:
17+
runs-on: ubuntu-latest
18+
19+
steps:
20+
- name: Checkout Code
21+
uses: actions/checkout@v4
22+
23+
- name: Set up Python
24+
uses: actions/setup-python@v5
25+
with:
26+
python-version: '3.x' # Use a specific version like '3.10', '3.11', or '3.12'
27+
28+
- name: Install MkDocs, Material for MkDocs, and PyMdown Extensions
29+
run: pip install mkdocs mkdocs-material pymdown-extensions
30+
31+
- name: Deploy Docs to GitHub Pages
32+
run: mkdocs gh-deploy --force --clean

‎README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,16 @@
44
[![HACS][hacsBadge]][hacsUrl]
55
[![Codacy][codacyBadge]][codacyUrl]
66

7-
![Preview GIF](./docs/preview.gif)
7+
![Preview GIF](docs/images/preview.gif)
88

99
<details>
1010
<summary>More images...</summary>
1111

12-
![Automatic](./docs/auto.png)
12+
![Automatic](docs/images/auto.png)
1313

14-
![Views](./docs/views.png)
14+
![Views](docs/images/views.png)
1515

16-
![customizable](./docs/customizable.png)
16+
![customizable](docs/images/customizable.png)
1717
</details>
1818

1919
## What is the Mushroom Dashboard Strategy?

‎docs/contributing.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# 🤝 Contributing to Mushroom Strategy
2+
3+
We love contributions from the community! Whether you're reporting a bug, suggesting a new feature, or submitting code
4+
changes, your help makes the Mushroom Strategy better for everyone.
5+
6+
Please take a moment to review this guide before making a contribution.
7+
8+
## 📜 Code of Conduct
9+
10+
To ensure a welcoming and inclusive environment, all contributors are expected to adhere to
11+
our [Code of Conduct](https://github.com/DigiLive/mushroom-strategy/blob/main/CODE_OF_CONDUCT.md). Please read it
12+
carefully.
13+
14+
---
15+
16+
## 🐞 Reporting Bugs
17+
18+
Found a bug? That's not ideal, but your report helps us squash it!
19+
20+
1. **Check existing issues:** Before opening a new issue, please search
21+
our GitHub [Issues](https://github.com/DigiLive/mushroom-strategy/issues)
22+
or [Discussions](https://github.com/DigiLive/mushroom-strategy/discussions) to see if the bug has already been
23+
reported.
24+
2. **Open a new issue:** If it's a new bug, please open
25+
a [new issue](https://github.com/DigiLive/mushroom-strategy/issues/new?template=bug_report.yml).
26+
3. **Provide details:** In your report, please include:
27+
28+
* A clear and concise description of the bug.
29+
* Steps to reproduce the behavior.
30+
* Expected behavior.
31+
* Screenshots or animated GIFs (if applicable).
32+
* Your Home Assistant version and Mushroom Strategy version.
33+
34+
---
35+
36+
## ✨ Suggesting Features
37+
38+
Have a great idea for a new feature or enhancement? We'd love to hear it!
39+
40+
1. **Check existing suggestions:** Search our GitHub [Issues](https://github.com/DigiLive/mushroom-strategy/issues)
41+
or [Discussions](https://github.com/DigiLive/mushroom-strategy/discussions) to see if the feature has already been
42+
requested.
43+
2. **Open a new issue:** If it's a new idea, open
44+
a [new issue](https://github.com/DigiLive/mushroom-strategy/issues/new?template=feature_request.yml).
45+
3. **Describe your idea:** Clearly explain the feature, why you think it's useful, and any potential use cases.
46+
47+
---
48+
49+
## 💻 Contributing Code
50+
51+
Want to get your hands dirty with the code? Awesome! We appreciate all code contributions.
52+
53+
1. **Fork the Repository:** Start by forking
54+
the [DigiLive/mushroom-strategy](https://github.com/DigiLive/mushroom-strategy) repository to your own GitHub
55+
account.
56+
2. **Clone Your Fork:** Clone your forked repository to your local machine.
57+
58+
```bash
59+
git clone https://github.com/YOUR_USERNAME/mushroom-strategy.git
60+
cd mushroom-strategy
61+
```
62+
63+
3. **Create a New Branch:** Create a new branch for your feature or bug fix. Use a descriptive name (e.g.,
64+
`feature/my-awesome-feature`, `bugfix/fix-admonition-rendering`).
65+
66+
```bash
67+
git checkout -b feature/my-new-feature
68+
```
69+
70+
4. **Set up Development Environment:**
71+
72+
* Ensure you have Node.js and npm installed.
73+
* Install project dependencies: `npm install`
74+
* You can build the strategy with `npm run build` (for production) or `npm run build-dev` (for development/testing).
75+
* Copy the built files to your Home Assistant's `www/community/mushroom-strategy` folder for testing.
76+
77+
5. **Make Your Changes:** Implement your bug fix or new feature.
78+
6. **Test Your Changes:** Thoroughly test your changes to ensure they work as expected and don't introduce new issues.
79+
7. **Commit Your Changes:**
80+
81+
* We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for clear commit history.
82+
* Example: `feat: add new card option` or `fix: correct card rendering issue`
83+
84+
```bash
85+
git add .
86+
git commit -m "feat: add super cool new feature"
87+
```
88+
89+
8. **Push to Your Fork:**
90+
91+
```bash
92+
git push origin feature/my-new-feature
93+
```
94+
95+
9. **Create a Pull Request (PR):**
96+
97+
* Go to your forked repository on GitHub.
98+
* You should see a prompt to create a pull request from your new branch to the `main` branch of
99+
`DigiLive/mushroom-strategy`.
100+
* Provide a clear title and description for your PR, referencing any related issues.
101+
* Be prepared to discuss your changes and address any feedback during the review process.
102+
103+
---
104+
105+
## 📄 Improving Documentation
106+
107+
Good documentation is vital! If you find typos, unclear sections, or want to add more examples, please open a pull
108+
request. The documentation is located in the `docs/` folder of this repository.
109+
110+
---
111+
112+
## 🌐 Translations
113+
114+
Help us make Mushroom Strategy accessible to more users around the world by contributing and improving translations!
115+
116+
Language tags have to follow [BCP 47](https://tools.ietf.org/html/bcp47).
117+
A list of most language tags can be found
118+
here: [IANA subtag registry](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
119+
Examples: fr, fr-CA, zh-Hans.
120+
121+
1. **Check for Existing Translations:** See if your language is already being worked on or exists.
122+
2. **Locate Translation Files:** Language files are found within the `src/translations` directory.
123+
Each language has its own `locale.json` file (e.g., `en.json`, `nl.json`, `pt-BR.json`).
124+
3. **Create or Update:**
125+
126+
* **To create a new language:** Copy an existing `.json` file (e.g., `en.json`), rename it to your language
127+
code (e.g., `de.json` for German), and translate the property values.
128+
* **To update an existing language:** Open the `.json` file for your language and update any missing or
129+
outdated translations.
130+
131+
4. **Submit a Pull Request:** Once your translations are complete, submit a pull request with your changes. Clearly
132+
state which language you are contributing to or updating.
133+
134+
!!! info
135+
**Integrating a new Translation:**
136+
137+
* For your new language file to be picked up, it needs to be imported and registered at file
138+
`src/utilities/localize.ts`.
139+
* You will need to add an `import` statement for your new `.json` file at the top, following the existing pattern.
140+
* Then, you'll need to add it to the `languages` map, associating the language code with the imported module.
141+
142+
**Special Handling for `language-country` Locales:**
143+
If you are adding a country-specific locale (e.g., `es-ES` for Spanish (Spain) or `en-GB` for English
144+
(United Kingdom)), you should create a file like `en-GB.json` in the `translations` folder. In
145+
`src/utilities/localize.ts`, you'll import it similarly and add it to the `languages` map using the full locale
146+
code.
147+
Please ensure you follow existing patterns for `language-country` codes, which typically use a hyphen (`-`) + a
148+
UPPER-cased country code in the file name and an underscore (`_`) + a lower-cased country code in the import key.
149+
150+
!!! example
151+
```typescript
152+
import * as en from '../translations/en.json';
153+
import * as pt_br from '../translations/pt-BR.json';
154+
155+
/** Registry of currently supported languages */
156+
const languages: Record<string, unknown> = {
157+
en,
158+
'pt-BR': pt_br,
159+
};
160+
```
161+
162+
---
163+
164+
## 🙏 Get Support
165+
166+
If you have questions about contributing or need help with your setup, please open
167+
a [discussion](https://github.com/DigiLive/mushroom-strategy/discussions) on our GitHub repository.

‎docs/faq.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
??? question "How do I add a device or entity to an area?"
2+
3+
You can add devices to an area by going to `Settings` found at the bottom of the sidebar.
4+
5+
1. Select `Devices & services`.
6+
2. Select `Devices` or `Entities`at the top.
7+
3. Choose the device or entity you wish to add to an area.
8+
4. Select :material-pencil: or :material-cog: in the top right corner.
9+
5. Choose an area in the area field.
10+
11+
!!! warning
12+
If you created an entity manually (in your `configuration.yaml`), you may need to create a `unique_id` before
13+
you can set an area to it.
14+
See Home Assistant's [documentation][uniqueIdUrl] for more info about unique ids.
15+
16+
??? question "How do I hide entities from the Strategy?"
17+
18+
When creating this dashboard for the first time, you might be overwhelmed by the number of entities.
19+
To reduce the number of entities shown, you can hide these entities by following the steps below:
20+
21+
1. Click and hold the entity.
22+
2. Click :material-cog: in the top right corner of the popup.
23+
3. Set `Visible` to `off`.
24+
25+
26+
!!! note
27+
If you don't want to hide the entity from all dashboards, you can use [Card Options][cardOptionsUrl] to hide
28+
specific entities and devices.
29+
30+
??? question "How do I get the id of entities, devices and areas?"
31+
32+
* Entity Id
33+
1. Select `Settings` at the bottom of the sidebar.
34+
2. Select `Devices & services`.
35+
3. Select `Entities` at the top.
36+
4. Choose the entity you want to get the id of.
37+
5. Click :material-cog: in the top right corner of the popup.
38+
39+
* Device Id
40+
1. Select `Settings` at the bottom of the sidebar.
41+
2. Select `Devices & services`.
42+
3. Select `Devices` at the top.
43+
4. Select the device you want to get the id of.
44+
5. The device id is shown as the **last** part of the url in the address bar.
45+
E.g.: `https://.../config/devices/device/h55b6k54j76g56`
46+
47+
* Area Id
48+
1. Select `Settings` at the bottom of the sidebar.
49+
2. Select `Areas`.
50+
3. Select :material-pencil: of the area you want to get the id of.
51+
52+
<!-- references -->
53+
54+
[uniqueIdUrl]: https://www.home-assistant.io/faq/unique_id
55+
56+
[cardOptionsUrl]: options/card-options.md

‎docs/full-example.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
Here is a full example using all the options provided with the strategy.
2+
3+
```yaml
4+
strategy:
5+
type: custom:mushroom-strategy
6+
options:
7+
views:
8+
light:
9+
order: 1
10+
title: illumination
11+
switches:
12+
hidden: true
13+
icon: mdi:toggle-switch
14+
home_view:
15+
hidden:
16+
- areasTitle
17+
- greeting
18+
stack_count:
19+
areas: [2, 1]
20+
persons: 3
21+
domains:
22+
_:
23+
hide_config_entities: true
24+
stack_count: 1
25+
light:
26+
order: 1
27+
stack_count: 2
28+
title: "My cool lights"
29+
chips:
30+
weather_entity: weather.forecast_home
31+
climate_count: false
32+
cover_count: false
33+
extra_chips:
34+
- type: conditional
35+
conditions:
36+
- entity: lock.front_door
37+
state: unlocked
38+
chip:
39+
type: entity
40+
entity: lock.front_door
41+
icon_color: red
42+
content_info: none
43+
icon: ''
44+
use_entity_picture: false
45+
tap_action:
46+
action: toggle
47+
- type: conditional
48+
conditions:
49+
- entity: cover.garage_door
50+
state_not: closed
51+
chip:
52+
type: entity
53+
entity: cover.garage_door
54+
icon_color: red
55+
content_info: none
56+
tap_action:
57+
action: toggle
58+
areas:
59+
_:
60+
type: default
61+
family_room_id:
62+
name: Family Room
63+
icon: mdi:television
64+
icon_color: green
65+
extra_cards:
66+
- type: custom:mushroom-chips-card
67+
chips:
68+
- type: entity
69+
entity: sensor.family_room_temperature
70+
icon: mdi:thermometer
71+
icon_color: pink
72+
alignment: center
73+
kitchen_id:
74+
name: Kitchen
75+
icon: mdi:silverware-fork-knife
76+
icon_color: red
77+
order: 1
78+
master_bedroom_id:
79+
name: Master Bedroom
80+
icon: mdi:bed-king
81+
icon_color: blue
82+
kids_bedroom_id:
83+
name: Kids Bedroom
84+
icon: mdi:flower-tulip
85+
icon_color: green
86+
card_options:
87+
fan.master_bedroom_fan:
88+
type: custom:mushroom-fan-card
89+
remote.harmony_hub_wk:
90+
hidden: true
91+
quick_access_cards:
92+
- type: custom:mushroom-cover-card
93+
entity: cover.garage_door
94+
show_buttons_control: true
95+
- type: horizontal-stack
96+
cards:
97+
- type: custom:mushroom-lock-card
98+
entity: lock.front_door
99+
- type: custom:mushroom-entity-card
100+
entity: sensor.front_door_lock_battery
101+
name: Battery
102+
extra_cards:
103+
- type: custom:xiaomi-vacuum-map-card
104+
map_source:
105+
camera: camera.xiaomi_cloud_map_extractor
106+
calibration_source:
107+
camera: true
108+
entity: vacuum.robot_vacuum
109+
vacuum_platform: default
110+
extra_views:
111+
- theme: Backend-selected
112+
title: Cool view
113+
path: cool-view
114+
icon: mdi:emoticon-cool
115+
badges: []
116+
cards:
117+
- type: markdown
118+
content: I am cool
119+
```

0 commit comments

Comments
 (0)