docs: restructure

13 files changed, 1258 insertions, 0 deletions

diff --git a/docs/guide/libraries/apps.md b/docs/guide/libraries/apps.md
new file mode 100644
index 0000000..c53daf0
--- /dev/null
+++ b/docs/guide/libraries/apps.md
@@ -0,0 +1,113 @@
+# Apps
+
+Library and CLI tool for querying and launching
+applications that have a corresponding `.desktop` file.
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala json-glib gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson valac libjson-glib-dev gobject-introspection
+```
+
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/apps
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Apps reference](https://aylur.github.io/libastal/apps).
+
+### CLI
+
+```sh
+astal-apps --help
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Apps from "gi://AstalApps"
+
+const apps = new Apps.Apps({
+    includeEntry: true,
+    includeExecutable: true,
+})
+
+for (const app of apps.fuzzy_query("spotify")) {
+    print(app.name)
+}
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalApps as Apps
+
+apps = Apps.Apps(
+    include_entry=True,
+    include_executable=True,
+)
+
+for app in apps.fuzzy_query("obsidian"):
+    print(app.get_name())
+
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local Apps = require("lgi").require("AstalApps")
+
+local apps = Apps.Apps({
+    include_entry = true,
+    include_executable = true,
+})
+
+for _, app in ipairs(apps:fuzzy_query("lutris")) do
+    print(app.name)
+end
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented, contributions are appreciated
+```
+
+:::
+
+:::info
+The fuzzy query uses [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance). I am not a mathematician, but if you know how to reimplement
+the logic of [fzf](https://github.com/junegunn/fzf) to make it better feel free to open PRs.
+:::
diff --git a/docs/guide/libraries/auth.md b/docs/guide/libraries/auth.md
new file mode 100644
index 0000000..1f07a17
--- /dev/null
+++ b/docs/guide/libraries/auth.md
@@ -0,0 +1,118 @@
+# Auth
+
+Library and CLI tool for authentication using [pam](https://github.com/linux-pam/linux-pam).
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson pam gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson pam-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+# Not yet documented
+```
+
+:::
+
+::: warning On NixOS you have to add `astal-auth` to `security.pam`.
+::: code-group
+
+```nix [configuration.nix]
+{
+  security.pam.services.astal-auth = {}
+}
+```
+
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/auth
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Auth reference](https://aylur.github.io/libastal/auth).
+
+### CLI
+
+```sh
+astal-auth --password my-password
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Auth from "gi://AstalAuth"
+
+Auth.Pam.authenticate("password", (_, task) => {
+    try {
+        AstalAuth.Pam.authenticate_finish(task)
+        print("authentication sucessful")
+    } catch (error) {
+        print(error)
+    }
+})
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalAuth as Auth
+
+def callback(_, task) -> None:
+    try:
+        Auth.Pam.authenticate_finish(task)
+        print("success")
+    except Exception as e:
+        print(e)
+
+Auth.Pam.authenticate("password", callback)
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local Auth = require("lgi").require("AstalAuth")
+
+Auth.Pam.authenticate("password", function(_, task)
+    local status, err = Auth.Pam.authenticate_finish(task)
+    if err ~= nil then
+        print(err)
+    else
+        print("success")
+    end
+end)
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/guide/libraries/battery.md b/docs/guide/libraries/battery.md
new file mode 100644
index 0000000..b42d747
--- /dev/null
+++ b/docs/guide/libraries/battery.md
@@ -0,0 +1,97 @@
+# Battery
+
+Library and CLI tool for monitoring [upowerd](https://upower.freedesktop.org/) devices.
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala json-glib gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson valac libjson-glib-dev gobject-introspection
+```
+
+:::
+
+::: info
+Although UPower is not a direct build dependency,
+it should be self-explanatory that the daemon is required to be available at runtime.
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/battery
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Battery reference](https://aylur.github.io/libastal/battery).
+
+### CLI
+
+```sh
+astal-battery --help
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Battery from "gi://AstalBattery"
+
+const battery = Battery.get_default()
+
+print(battery.percentage)
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalBattery as Battery
+
+battery = Battery.get_default()
+
+print(battery.get_percentage())
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local Battery = require("lgi").require("AstalBattery")
+
+local battery = Battery.get_default()
+
+print(battery.percentage)
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/guide/libraries/bluetooth.md b/docs/guide/libraries/bluetooth.md
new file mode 100644
index 0000000..04d9db2
--- /dev/null
+++ b/docs/guide/libraries/bluetooth.md
@@ -0,0 +1,104 @@
+# Bluetooth
+
+Library for monitoring [bluez](https://www.bluez.org/) over dbus.
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc valac gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson valac gobject-introspection
+```
+
+:::
+
+::: info
+Although bluez is not a direct build dependency,
+it should be self-explanatory that the daemon is required to be available at runtime.
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/bluetooth
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Bluetooth reference](https://aylur.github.io/libastal/bluetooth).
+
+### CLI
+
+There is no CLI for this library, use the one provided by bluez.
+
+```sh
+bluetoothctl --help
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Bluetooth from "gi://AstalBluetooth"
+
+const bluetooth = Bluetooth.get_default()
+
+for (const device of bluetooth.get_devices()) {
+    print(device.name)
+}
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalBluetooth as Bluetooth
+
+bluetooth = Bluetooth.get_default()
+
+for device in bluetooth.get_devices():
+    print(device.get_name())
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local Bluetooth = require("lgi").require("AstalBluetooth")
+
+local bluetooth = Bluetooth.get_default()
+
+for _, d in ipairs(bluetooth.devices) do
+    print(d.name)
+end
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/guide/libraries/hyprland.md b/docs/guide/libraries/hyprland.md
new file mode 100644
index 0000000..faf9e50
--- /dev/null
+++ b/docs/guide/libraries/hyprland.md
@@ -0,0 +1,97 @@
+# Hyprland
+
+Library and CLI tool for monitoring the [Hyprland socket](https://wiki.hyprland.org/IPC/).
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala json-glib gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson valac libjson-glib-dev gobject-introspection
+```
+
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/hyprland
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Hyprland reference](https://aylur.github.io/libastal/hyprland).
+
+### CLI
+
+```sh
+astal-hyprland # starts monitoring
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Hyprland from "gi://AstalHyprland"
+
+const hyprland = Hyprland.get_default()
+
+for (const client of hyprland.get_clients()) {
+    print(client.title)
+}
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalHyprland as Hyprland
+
+hyprland = Hyprland.get_default()
+
+for client in hyprland.get_clients():
+    print(client.get_title())
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local Hyprland = require("lgi").require("AstalHyprland")
+
+local hyprland = Hyprland.get_default()
+
+for _, c in ipairs(hyprland.clients) do
+    print(c.title)
+end
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/guide/libraries/mpris.md b/docs/guide/libraries/mpris.md
new file mode 100644
index 0000000..dfe7956
--- /dev/null
+++ b/docs/guide/libraries/mpris.md
@@ -0,0 +1,100 @@
+# Mpris
+
+Library and CLI tool for interacting and monitoring media players
+exposing an mpris interface through dbus.
+
+An alternative for [playerctl](https://github.com/altdesktop/playerctl) that better integrates
+with astal.
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala json-glib gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson valac libjson-glib-dev gobject-introspection
+```
+
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/mpris
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Mpris reference](https://aylur.github.io/libastal/mpris).
+
+### CLI
+
+```sh
+astal-mpris --help
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Mpris from "gi://AstalMpris"
+
+const spotify = Mpris.Player.new("spotify")
+
+if (spotify.available)
+    print(spotify.title)
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalMpris as Mpris
+
+spotify = Mpris.Player.new("spotify")
+
+if spotify.get_available():
+    print(spotify.get_title())
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local Mpris = require("lgi").require("AstalMpris")
+
+local spotify = Mpris.Player.new("spotify")
+
+if spotify.available then
+    print(spotify.title)
+end
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/guide/libraries/network.md b/docs/guide/libraries/network.md
new file mode 100644
index 0000000..afeb5d2
--- /dev/null
+++ b/docs/guide/libraries/network.md
@@ -0,0 +1,94 @@
+# Network
+
+Wrapper library over [networkmanager](https://networkmanager.dev/) to better integrate with Astal.
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala libnm gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc valac NetworkManager-libnm-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson valac libnm-dev gobject-introspection
+```
+
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/network
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Network reference](https://aylur.github.io/libastal/network).
+
+### CLI
+
+There is no CLI for this library, use the one provided by networkmanager.
+
+```sh
+nmcli --help
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Network from "gi://AstalNetwork"
+
+const network = Network.get_default()
+
+print(network.wifi.ssid)
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalNetwork as Network
+
+network = Network.get_default()
+
+print(network.get_wifi().get_ssid())
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local Network = require("lgi").require("AstalNetwork")
+
+local network = Network.get_default()
+
+print(network.wifi.ssid)
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/guide/libraries/notifd.md b/docs/guide/libraries/notifd.md
new file mode 100644
index 0000000..7e02149
--- /dev/null
+++ b/docs/guide/libraries/notifd.md
@@ -0,0 +1,106 @@
+# Notifd
+
+A [notification daemon](https://specifications.freedesktop.org/notification-spec/latest/) implementation as a library and CLI tool.
+
+## How it works
+
+The first instantiation of the [Notifd](https://aylur.github.io/libastal/notifd/class.Notifd.html) class will become the daemon and every subsequent instantiation will queue up to act as the daemon and will act as a client in the meantime. This means this library can be used throughout multiple processes.
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala gdk-pixbuf2 json-glib gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc valac gdk-pixbuf2-devel json-glib-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson valac libgdk-pixbuf-2.0-dev libjson-glib-dev gobject-introspection
+```
+
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/notifd
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Notifd reference](https://aylur.github.io/libastal/notifd).
+
+### CLI
+
+```sh
+astal-notifd --help
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Notifd from "gi://AstalNotifd"
+
+const notifd = Notifd.get_default()
+
+notifd.connect("notified", (_, id) => {
+    const n = notifd.get_notification(id)
+    print(n.summary, n.body)
+})
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalNotifd as Notifd
+
+notifd = Notifd.get_default()
+
+def on_notified(_, id):
+    n = notifd.get_notification(id)
+    print(n.get_body(), n.get_body())
+
+notifd.connect("notified", on_notified)
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local Notifd = require("lgi").require("AstalNotifd")
+
+local notifd = Notifd.get_default()
+
+notifd.on_notified = function(_, id)
+    local n = notifd.get_notification(id)
+    print(n.body, n.summary)
+end
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/guide/libraries/powerprofiles.md b/docs/guide/libraries/powerprofiles.md
new file mode 100644
index 0000000..8571c29
--- /dev/null
+++ b/docs/guide/libraries/powerprofiles.md
@@ -0,0 +1,97 @@
+# Power Profiles
+
+Library and CLI tool for monitoring [upowerd](https://upower.freedesktop.org/) powerprofiles.
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala json-glib gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc valac json-glib-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson valac libjson-glib-dev gobject-introspection
+```
+
+:::
+
+::: info
+Although UPower is not a direct build dependency,
+it should be self-explanatory that the daemon is required to be available at runtime.
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/powerprofiles
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [PowerProfiles reference](https://aylur.github.io/libastal/powerprofiles).
+
+### CLI
+
+```sh
+astal-power-profiles --help
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import PowerProfiles from "gi://AstalPowerProfiles"
+
+const powerprofiles = PowerProfiles.get_default()
+
+print(powerprofiles.activeProfile)
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalPowerProfiles as PowerProfiles
+
+powerprofiles = PowerProfiles.get_default()
+
+print(powerprofiles.get_active_profile())
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local PowerProfiles = require("lgi").require("AstalPowerProfiles")
+
+local powerprofiles = PowerProfiles.get_default()
+
+print(powerprofiles.active_profile)
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/guide/libraries/references.md b/docs/guide/libraries/references.md
new file mode 100644
index 0000000..8f2bd02
--- /dev/null
+++ b/docs/guide/libraries/references.md
@@ -0,0 +1,44 @@
+# References
+
+The references of the libraries are annotated for the C language.
+Reading their documentation will vary depending on the language they are used in.
+
+<!--TODO: list some examples on how to read docs,-->
+<!--for example the difference between C enums and gjs enums-->
+
+## Additional references
+
+### GJS
+
+- [gjs-docs.gnome.org](https://gjs-docs.gnome.org/): Library references annotated for GJS
+- [gjs.guide](https://gjs.guide/): GJS and GObject guide
+
+### Python
+
+- [pgi-docs](https://lazka.github.io/pgi-docs/): Library references annotated for Python
+- [pygobject.gnome.org](https://pygobject.gnome.org/): PyGObject reference and guide
+
+### Lua
+
+- [lua-lgi docs](https://github.com/lgi-devs/lgi/tree/master/docs): GObject bindings guide for Lua
+
+### Vala
+
+- [vala.dev](https://vala.dev/): Guide for the Vala language
+- [valadoc.org](https://valadoc.org/): Library references annotated for Vala
+
+## Astal Libraries
+
+- [Astal](https://aylur.github.io/libastal): libastal the core library, which has the widgets and utilites
+- [Apps](https://aylur.github.io/libastal/apps): Library and cli tool for querying applications
+- [Auth](https://aylur.github.io/libastal/auth): Authentication library using PAM
+- [Battery](https://aylur.github.io/libastal/battery): DBus proxy library for upower daemon
+- [Bluetooth](https://aylur.github.io/libastal/bluetooth): Library to control bluez over dbus
+- [Hyprland](https://aylur.github.io/libastal/hyprland): Library and cli tool for Hyprland IPC socket
+- [Mpris](https://aylur.github.io/libastal/mpris): Library and cli tool for controlling media players
+- [Network](https://aylur.github.io/libastal/network): NetworkManager wrapper library
+- [Notifd](https://aylur.github.io/libastal/notifd): A notification daemon library and cli tool
+- [PowerProfiles](https://aylur.github.io/libastal/powerprofiles): Library and cli to control upowerd powerprofiles
+- [River](https://aylur.github.io/libastal/river): Library and cli tool for getting status information of the river wayland compositor
+- [Tray](https://aylur.github.io/libastal/tray): A systemtray library and cli tool
+- [WirePlumber](https://aylur.github.io/libastal/wireplumber): A library for audio control using wireplumber
diff --git a/docs/guide/libraries/river.md b/docs/guide/libraries/river.md
new file mode 100644
index 0000000..4818d0b
--- /dev/null
+++ b/docs/guide/libraries/river.md
@@ -0,0 +1,97 @@
+# River
+
+Library and CLI tool for monitoring the [River Wayland Compositor](https://isaacfreund.com/software/river/).
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson json-glib gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc json-glib-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson libjson-glib-dev gobject-introspection
+```
+
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/river
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [River reference](https://aylur.github.io/libastal/river).
+
+### CLI
+
+```sh
+astal-river --help
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import River from "gi://AstalRiver"
+
+const river = River.get_default()
+
+for (const output of river.get_outputs()) {
+    print(output.name)
+}
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalRiver as River
+
+river = River.get_default()
+
+for output in river.get_outputs():
+    print(output.get_name())
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local River = require("lgi").require("AstalRiver")
+
+local river = River.River.get_default()
+
+for _, o in ipairs(river.outputs) do
+    print(o.name)
+end
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/guide/libraries/tray.md b/docs/guide/libraries/tray.md
new file mode 100644
index 0000000..c8d093b
--- /dev/null
+++ b/docs/guide/libraries/tray.md
@@ -0,0 +1,97 @@
+# Tray
+
+Library for managing the systemtray by implementing the [StatusNotifierItem](https://www.freedesktop.org/wiki/Specifications/StatusNotifierItem/) protocol.
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson gtk3 gobject-introspection libdbusmenu-gtk3
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc gtk3-devel libdbusmenu-gtk3 gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+sudo apt install meson libgtk-3-dev libdbusmenu-gtk3-dev gobject-introspection
+```
+
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/tray
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Tray reference](https://aylur.github.io/libastal/tray).
+
+### CLI
+
+```sh
+astal-tray --help
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Tray from "gi://AstalTray"
+
+const tray = Tray.get_default()
+
+for (const item of tray.get_items()) {
+    print(item.title)
+}
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalTray as Tray
+
+tray = Tray.get_default()
+
+for item in tray.get_items():
+    print(item.title)
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local Tray = require("lgi").require("AstalTray")
+
+local tray = Tray.get_default()
+
+for _, i in ipairs(tray.items) do
+    print(i.title)
+end
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::
diff --git a/docs/guide/libraries/wireplumber.md b/docs/guide/libraries/wireplumber.md
new file mode 100644
index 0000000..5f1daab
--- /dev/null
+++ b/docs/guide/libraries/wireplumber.md
@@ -0,0 +1,94 @@
+# Wire Plumber
+
+Wrapper library over [wireplumber](https://pipewire.pages.freedesktop.org/wireplumber/) to better integrate with Astal.
+
+## Installation
+
+1. install dependencies
+
+:::code-group
+
+```sh [<i class="devicon-archlinux-plain"></i> Arch]
+sudo pacman -Syu meson vala wireplumber gobject-introspection
+```
+
+```sh [<i class="devicon-fedora-plain"></i> Fedora]
+sudo dnf install meson gcc valac wireplumber-devel gobject-introspection-devel
+```
+
+```sh [<i class="devicon-ubuntu-plain"></i> Ubuntu]
+# Not yet documented
+```
+
+:::
+
+2. clone repo
+
+```sh
+git clone https://github.com/aylur/astal.git
+cd astal/lib/wireplumber
+```
+
+3. install
+
+```sh
+meson setup build
+meson install -C build
+```
+
+:::tip
+Most distros recommend manual installs in `/usr/local`,
+which is what `meson` defaults to. If you want to install to `/usr`
+instead which most package managers do, set the `prefix` option:
+
+```sh
+meson setup --prefix /usr build
+```
+
+:::
+
+## Usage
+
+You can browse the [Wireplumber reference](https://aylur.github.io/libastal/wireplumber).
+
+### CLI
+
+There is no CLI for this library, use the one provided by wireplumber.
+
+```sh
+wpctl --help
+```
+
+### Library
+
+:::code-group
+
+```js [<i class="devicon-javascript-plain"></i> JavaScript]
+import Wp from "gi://AstalWp"
+
+const audio = Wp.get_default().audio
+
+print(audio.default_speaker.volume)
+```
+
+```py [<i class="devicon-python-plain"></i> Python]
+from gi.repository import AstalWp as Wp
+
+audio = Wp.get_default().get_audio()
+
+print(audio.get_default_speaker().get_volume())
+```
+
+```lua [<i class="devicon-lua-plain"></i> Lua]
+local Wp = require("lgi").require("AstalWp")
+
+local audio = Wp.get_default().audio
+
+print(audio.default_speaker.volume)
+```
+
+```vala [<i class="devicon-vala-plain"></i> Vala]
+// Not yet documented
+```
+
+:::