Bring documentation into a much better place

.github/workflows/checks.yml

@@ -33,13 +33,13 @@ jobs:
     runs-on: ubuntu-24.04
 
     steps:
-      - name: Checkout
+      - name: Checkout the code
         uses: actions/checkout@v4
 
-      - name: Setup Python
+      - name: Set up Python
         uses: actions/setup-python@v5
 
-      - name: Pre-commit
+      - name: Run pre-commit
         uses: pre-commit/[email protected]
 
   pytest:
@@ -74,13 +74,37 @@ jobs:
       - name: Run pytest
         run: poetry run pytest
 
+  usage:
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout the code
+        uses: actions/checkout@v4
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          cache: poetry
+
+      - name: Install dependencies
+        run: poetry install
+
+      - name: Check usage.md is up-to-date
+        run: |
+          ./generate-usage.sh
+          git diff --exit-code
+
   all-checks-passed:
     if: always()
 
     needs:
     - mypy
     - pre-commit
     - pytest
+    - usage
 
     runs-on: ubuntu-24.04
 

README.md

@@ -3,9 +3,48 @@ Alga
 
 A command line utility for controlling a LG webOS TV over the network.
 
-It is still in it's early stages of development but the implemented functionality should work.
 
-Work yet to do:
----------------
+Installing
+----------
 
-* Add tests for websocket communication and TV setup
+Alga is [available on PyPI](https://pypi.org/project/alga/).
+I would recommend installing it via [pipx](https://pipx.pypa.io/stable/):
+
+```shell
+$ pipx install alga
+```
+
+
+Setup
+-----
+
+The first time you use the utility, you will need to setup a connection to the TV.
+With the TV on, run `alga setup [hostname/IP]`.
+This will bring up a prompt on the TV asking if you want to accept the pairing.
+When accepted, Alga will be ready to use.
+
+If no hostname or IP address is provided to `alga setup`, it will be default try to connect to "lgwebostv" which should work.
+
+The hostname, a key and MAC address will be written to `~/.config/alga/config.json` for future use.
+
+Note: It's currently only possible to pair Alga with one TV at a time.
+Let me know if this is a deal breaker for you.
+
+
+Usage
+-----
+
+See [usage](usage.md) for a list of available commands.
+
+
+Development
+-----------
+
+The code base is fully type annotated and test coverage is being enforced.
+Types can be checked via `poetry run mypy .` and tests via `poetry run pytest`.
+
+Tests are run for each of the supported Python versions in CI.
+
+[pre-commit](https://pre-commit.com/) used to run Ruff for linting and formatting.
+
+`usage.md` is updated via `./generate-usage.sh`.

generate-usage.sh

@@ -0,0 +1 @@
+typer alga.__main__ utils docs --name alga --title "Available commands" --output usage.md