added a doc page for the add-on

docs/ADDON.md

@@ -0,0 +1,128 @@
+# AppDaemon Add-on
+
+The [AppDaemon python package] and the [AppDaemon Add-on for Home Assistant] (maintained by [Frenck]) have no official relationship. They have different versions and release schedules, but are both commonly run using Docker containers. The AppDaemon project provides a [Docker container], and the add-on uses another one that includes some things to help it integrate with Home Assistant's Supervisor.
+
+[AppDaemon python package]: https://pypi.org/project/appdaemon/
+[AppDaemon Add-on for Home Assistant]: https://github.com/hassio-addons/addon-appdaemon
+[Frenck]: https://github.com/frenck
+[Docker container]: https://hub.docker.com/r/acockburn/appdaemon
+
+:::{tip}
+[Install AppDaemon Add-on](https://my.home-assistant.io/redirect/supervisor_addon/?addon=a0d7b954_appdaemon&repository_url=https%3A%2F%2Fgithub.com%2Fhassio-addons%2Frepository)
+:::
+
+:::{note}
+- **Add-on Repository**: [hassio-addons/addon-appdaemon](https://github.com/hassio-addons/addon-appdaemon)
+- **AppDaemon Repository**: [AppDaemon/appdaemon](https://github.com/AppDaemon/appdaemon)
+:::
+
+## Workflow
+
+An easy way to work with the AppDaemon config files is to expose them with a [Samba] share, which uses [smb] to make folders accessible across a network. This is an old, well-established standard that works really well across platforms. The Samba add-on makes the AppDaemon config folder accessible at `addon_configs/a0d7b954_appdaemon`. That share can be mounted on your local system as a network drive where it can be accessed with an IDE like [VSCode] or [PyCharm].
+
+See [this section](https://www.home-assistant.io/common-tasks/os/#installing-and-using-the-samba-add-on) of the Home Assistant docs for more information about accessing samba shares.
+
+[Samba]: https://www.samba.org/
+[smb]: https://en.wikipedia.org/wiki/Server_Message_Block
+[VSCode]: https://code.visualstudio.com/
+[PyCharm]: https://www.jetbrains.com/pycharm/
+
+:::{tip}
+[Install Samba Add-on](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_samba) [(configuration docs)](https://github.com/home-assistant/addons/blob/master/samba/DOCS.md)
+:::
+
+
+
+## Paths
+
+| Name                  | Inside Container | Samba                             | Host                                                  |
+| --------------------- | ---------------- | --------------------------------- | ----------------------------------------------------- |
+| Home Assistant config | /homeassistant   | /config                           | /mnt/data/supervisor/homeassistant                    |
+| AppDaemon config      | /config          | /addon_configs/a0d7b954_appdaemon | /mnt/data/supervisor/addon_configs/a0d7b954_appdaemon |
+| Home Assistant Media  | /media           | /media                            | /mnt/data/supervisor/media                            |
+| Home Assistant Share  | /share           | /share                            | /mnt/data/supervisor/share                            |
+
+## Config
+
+### Token
+
+The authentication token for the Hass plugin is automatically provided by the Hass Supervisor using the `SUPERVISOR_TOKEN` environment variable.
+
+### System Packages
+
+System packages are installed into the container environment using [apk] before AppDaemon is launched. Anything from the [Alpine Package Index] can be used.
+
+For example, to install [pandas]:
+```
+py3-pandas
+```
+
+[pandas]: https://pandas.pydata.org/
+[apk]: https://wiki.alpinelinux.org/wiki/Alpine_Package_Keeper
+[Alpine Package Index]: https://pkgs.alpinelinux.org/packages?branch=v3.22
+
+:::{tip}
+Many python packages can be installed this way, which is much faster and more reliable than using pip. The packages usually have a <a href="https://pkgs.alpinelinux.org/packages?name=py3*&branch=v3.22"><code>py3-*</code>prefix</a>.
+:::
+
+### Python Packages
+
+Python packages are installed into the container environment using pip before AppDaemon is launched. Any package on PyPI can be used. Pip also [supports targeting VCS systems](https://pip.pypa.io/en/stable/topics/vcs-support/#supported-vcs), so any python packages on GitHub can be installed directly in several ways:
+
+- `git+<github_url>@<branch>`
+- `git+<github_url>@<short commit hash>`
+- `<github_url>/archive/refs/heads/<long commit hash>.zip`
+
+![appdaemon add-on config](./images/appdaemon_add-on_cfg.png)
+
+:::{tip}
+The add-on will use the version of AppDaemon installed from GitHub in the example screenshot above. This makes it easy to control which version of AppDaemon the add-on uses.
+
+- `git+https://github.com/AppDaemon/appdaemon@dev`
+- `git+https://github.com/AppDaemon/appdaemon@4.4.2`
+- `git+https://github.com/AppDaemon/appdaemon@beaa161`
+
+:::
+
+
+## Docker Mechanics
+
+This section shows some of how the AppDaemon add-on container works in the supervised environment of [Hass OS] and is just for informational purposes. It uses the [Advanced SSH & Web Terminal Add-on] to inspect the Docker container.
+
+[Hass OS]: https://github.com/home-assistant/operating-system
+[Advanced SSH & Web Terminal Add-on]: https://github.com/hassio-addons/addon-ssh/tree/main
+
+:::{tip}
+[Install Advanced SSH & Web Terminal Add-on](https://my.home-assistant.io/redirect/supervisor_addon/?addon=a0d7b954_ssh&repository_url=https%3A%2F%2Fgithub.com%2Fhassio-addons%2Frepository)
+:::
+
+:::{warning}
+Protection mode has to be disabled for the SSH add-on for the following instructions to work. It's recommended to only disable it temporarily. Proceed carefully and at your own risk.
+:::
+
+**Check the status of the AppDaemon container**
+
+```zsh
+docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Status}}" | grep appdaemon
+```
+
+**Check the AppDaemon container logs**
+```zsh
+docker logs --tail 10 addon_a0d7b954_appdaemon
+```
+
+**Enter the AppDaemon container**
+```zsh
+docker exec -it addon_a0d7b954_appdaemon /bin/bash
+```
+
+**Show volume mounts from the AppDaemon container**
+```zsh
+docker inspect --format='{{json .Mounts}}' addon_a0d7b954_appdaemon | \
+    jq -r '.[] | select(.Type == "bind") | [.Destination, .Source] | @tsv'
+```
+
+**View installed Python packages**
+```zsh
+docker exec addon_a0d7b954_appdaemon pip list
+```

docs/conf.py

@@ -35,6 +35,11 @@
 
 copybutton_exclude = '.linenos, .gp'
 
+# -- MyST configuration ------------------------------------------------------
+myst_enable_extensions = [
+    "colon_fence",
+]
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 

docs/index.rst

@@ -63,6 +63,7 @@ Contents:
    INSTALL
    CONFIGURE
    DOCKER_TUTORIAL
+   ADDON
    HASS_TUTORIAL
    APPGUIDE
    COMMUNITY_TUTORIALS