From c06b70117f89af0055ef77d64852fd762f1ff375 Mon Sep 17 00:00:00 2001 From: Joshua Rich Date: Fri, 29 Sep 2023 04:47:05 +0000 Subject: [PATCH] docs(all): restructure and minor fixes --- .vscode/ltex.dictionary.en-AU.txt | 2 + README.md | 37 +++++++++++-------- docs/README.md | 16 ++++++++ .../{development.md => development/README.md} | 8 ++-- docs/{ => development}/agent.md | 0 5 files changed, 44 insertions(+), 19 deletions(-) create mode 100644 .vscode/ltex.dictionary.en-AU.txt create mode 100644 docs/README.md rename docs/{development.md => development/README.md} (92%) rename docs/{ => development}/agent.md (100%) diff --git a/.vscode/ltex.dictionary.en-AU.txt b/.vscode/ltex.dictionary.en-AU.txt new file mode 100644 index 000000000..29f3f7c2f --- /dev/null +++ b/.vscode/ltex.dictionary.en-AU.txt @@ -0,0 +1,2 @@ +Fyne +Hass diff --git a/README.md b/README.md index 8e4741ad9..120ecbe11 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,11 @@ -# go-hass-app + + +# Go Hass Agent ![MIT](https://img.shields.io/github/license/joshuar/go-hass-agent) ![GitHub last commit](https://img.shields.io/github/last-commit/joshuar/go-hass-agent) @@ -50,8 +57,8 @@ See also the [FAQ](docs/faq.md). ## 🤝 Compatibility Currently, only Linux is supported. Though the code is designed to be extensible -to other operating systems. See [the development docs](docs/development.md) for -details on how to extend for other operating systems. +to other operating systems. See development information in the +[docs](docs/README.md) for details on how to extend for other operating systems. ## ⬇️ Installation @@ -65,20 +72,20 @@ distribution: - For **Arch**, use the `.tar.zst`. For other distributions not listed above, you can try the binary, or build it -yourself from source (see [development](docs/development.md)). Note that while +yourself from source (see development [docs](docs/README.md)). Note that while Go is known for statically compiled binaries that "run anywhere", the Fyne UI -toolkit used by **go-hass-agent** makes use of shared libraries that may need to +toolkit used by Go Hass Agent makes use of shared libraries that may need to be installed as well. ## 🖱️ Usage -**go-hass-agent** runs as a tray icon by default. It is operating system, +Go Hass Agent runs as a tray icon by default. It is operating system, distribution and desktop-environment agnostic and should manifest itself in any tray of any desktop environment. ### First-run -On first-run, **go-hass-agent** will display a window where you will need to enter +On first-run, Go Hass Agent will display a window where you will need to enter some details, so it can register itself with a Home Assistant instance to be able to report sensors and receive notifications. @@ -89,14 +96,14 @@ able to report sensors and receive notifications. - A long-lived access token. You can generate one on your [account profile page](https://www.home-assistant.io/docs/authentication/#your-account-profile). - The web address (URL) on which a Home Assistant instance can be found. - - **go-hass-agent** will try to auto-detect this for you, and you can select it in + - Go Hass Agent will try to auto-detect this for you, and you can select it in the _Auto-discovered servers_ list. Otherwise, you will need to select _Use Custom Server?_, and enter the details manually in _Manual Server Entry_. When you have entered all the details, click **Submit** and the agent should start running and reporting sensors to the Home Assistant instance. -As alternative, you can register **go-hass-agent** on the command-line with by +As alternative, you can register Go Hass Agent on the command-line with by running: ```shell @@ -108,7 +115,7 @@ Assistant instance, `_URL_`. ### Regular Usage -When running, **go-hass-agent** will appear as a device under the [Mobile +When running, Go Hass Agent will appear as a device under the [Mobile App](https://www.home-assistant.io/integrations/mobile_app) integration in your Home Assistant instance. It should also report a list of sensors/entities you can use in any automations, scripts, dashboards and other parts of Home @@ -116,24 +123,24 @@ Assistant. ### Running Headless -**go-hass-agent** can run in a “headless” mode, without any GUI elements, by +Go Hass Agent can run in a “headless” mode, without any GUI elements, by specifying the `-t` or `--terminal` command-line option. On Linux systems, There is also a systemd service file that can be used for automatic start-up, installed (but not activated by default) in `/usr/lib/systemd/system`. ## 🧑‍🤝‍🧑 Contributing -### 🏗️ Development +### Development I would welcome your contribution! If you find any improvement or issue you want to fix, feel free to send a pull request! Some documentation for development can be found in -the [development docs](docs/development.md). There is information for developing -**go-hass-agent** for different operating systems as well as adding additional +the [docs](docs/README.md). There is information for developing +Go Hass Agent for different operating systems as well as adding additional sensors. This might help anyone to look to contribute, extend or fork this tool. -### 🌐 Translations +### Translations While this application does not have many points where text is displayed to the end user (logging aside), translation is supported through the `language` diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..cff9e9038 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,16 @@ + + +# Go Hass Agent Docs + +- [FAQ](faq.md). + +## Development + +- [General Development Notes](development/README.md). +- [Agent development](development/agent.md). +- [Adding Sensors](development/sensors.md). diff --git a/docs/development.md b/docs/development/README.md similarity index 92% rename from docs/development.md rename to docs/development/README.md index 637dc6444..26ff389e8 100644 --- a/docs/development.md +++ b/docs/development/README.md @@ -5,11 +5,11 @@ https://opensource.org/licenses/MIT --> -# go-hass-agent Development +# Go Hass Agent Development Notes ## Build Requirements -**go-hass-agent** has a number of build requirements external to `go.mod` that +Go Hass Agent has a number of build requirements external to `go.mod` that need to be installed: - [stringer](https://pkg.go.dev/golang.org/x/tools/cmd/stringer). @@ -39,7 +39,7 @@ container, as it is exposed as per above. ## Building -**go-hass-agent** makes use of `go generate` to generate some of the code. A typical build process would be: +Go Hass Agent makes use of `go generate` to generate some of the code. A typical build process would be: ```shell go generate ./... @@ -48,7 +48,7 @@ go build ## Packaging -**go-hass-agent** uses [Goreleaser](https://goreleaser.com/intro/) to create +Go Hass Agent uses [Goreleaser](https://goreleaser.com/intro/) to create packages for Fedora, Arch and Ubuntu and [fyne-cross](https://github.com/fyne-io/fyne-cross) to create packages for Debian. diff --git a/docs/agent.md b/docs/development/agent.md similarity index 100% rename from docs/agent.md rename to docs/development/agent.md