docs: reference links

docs/astro.config.mjs

@@ -1,12 +1,6 @@
 import { defineConfig } from "astro/config"
 import starlight from "@astrojs/starlight"
 
-const directories = [
-    ["Getting Started", "/getting-started"],
-    ["AGS", "/ags"],
-    ["Libraries", "/libraries"],
-]
-
 export default defineConfig({
     site: "https://aylur.github.io",
     base: "astal",
@@ -22,10 +16,29 @@ export default defineConfig({
             },
             customCss: ["./src/style.css"],
             favicon: "./favicon.ico",
-            sidebar: directories.map(([label, directory]) => ({
-                label,
-                autogenerate: { directory },
-            })),
+            sidebar: [
+                { label: "Getting Started", autogenerate: { directory: "/getting-started" } },
+                { label: "AGS", autogenerate: { directory: "/ags" } },
+                {
+                    label: "Libraries",
+                    items: [
+                        "libraries/references",
+                        { label: "Astal", link: "/reference" },
+                        { label: "Apps", link: "/reference/apps" },
+                        { label: "Auth", link: "/reference/auth" },
+                        { label: "Battery", link: "/reference/battery" },
+                        { label: "Bluetooth", link: "/reference/bluetooth" },
+                        { label: "Hyprland", link: "/reference/hyprland" },
+                        { label: "Mpris", link: "/reference/mpris" },
+                        { label: "Network", link: "/reference/network" },
+                        { label: "Notifd", link: "/reference/notifd" },
+                        { label: "PowerProfiles", link: "/reference/powerprofiles" },
+                        { label: "River", link: "/reference/river" },
+                        { label: "Tray", link: "/reference/tray" },
+                        { label: "WirePlumber", link: "/reference/wireplumber" },
+                    ],
+                }
+            ]
         }),
     ],
 })

docs/src/content/docs/ags/cli-app.md

@@ -5,7 +5,7 @@ sidebar:
     order: 3
 ---
 
-`App` is a singleton **instance** of [Astal.Application](/libastal/class.Application.html).
+`App` is a singleton **instance** of [Astal.Application](/astal/reference/class.Application.html).
 
 ```tsx
 import { App } from "astal"

docs/src/content/docs/ags/theming.md

@@ -79,7 +79,7 @@ App.reset_css() // reset if need
 ```
 
 :::caution
-`App.apply_css` will apply over other stylesheets applied before.
+`App.apply_css` will apply on top of other stylesheets applied before.
 You can reset stylesheets with `App.resetCss`
 :::
 

docs/src/content/docs/ags/variable.md

@@ -37,7 +37,7 @@ Widget.Label({
 
 :::caution
 Make sure to make the transform functions pure. The `.get()` function can be called
-anytime by `astal` especially when `deriving`.
+anytime by `astal` especially when `deriving`, so make sure there are no sideeffects.
 :::
 
 ## Composing variables

docs/src/content/docs/ags/widget.md

@@ -16,7 +16,7 @@ These are properties that Astal.js additionally adds to Gtk.Widgets
 
 To have a full list of available properties, reference the documentation of the widget.
 
-- [Astal widgets](/libastal/#classes)
+- [Astal widgets](/astal/reference#classes)
 - [Gtk widgets](https://docs.gtk.org/gtk3/#classes)
 
 You can check the [source code](https://github.com/aylur/astal/blob/main/gjs/src/widgets.ts) to have a full list of builtin widgets.
@@ -97,28 +97,54 @@ function MyWidget() {
 
 ## How to use non builtin Gtk widgets
 
+Using `Widget.astalify` you can setup widget constructors to behave like builtin widgets.
+The `astalify` function will apply the following:
+
+- set `visible` to true by default (Gtk3 widgets are invisible by default)
+- make gobject properties accept and consume `Binding` objects
+- add properties and methods listed above
+- proxify the constructor so the `new` keyword is not needed
+- sets up signal handlers that are passed as props prefixed with `on`
+
 ```tsx
-import { astalify, Gtk } from "astal"
+import { Widget, Gtk } from "astal"
 
 // define its props, constructor and type
-export type ColorButtonProps = Widget.ConstructProps<Gtk.ColorButton, Gtk.ColorButton.ConstructorProps>
-export const ColorButton = Widget.astalify<typeof Gtk.ColorButton, ColorButtonProps, "ColorButton">(Gtk.ColorButton)
+export type ColorButtonProps = Widget.ConstructProps<
+    Gtk.ColorButton,
+    Gtk.ColorButton.ConstructorProps,
+    { onColorSet: [] }
+>
+export const ColorButton = Widget.astalify<
+    typeof Gtk.ColorButton,
+    ColorButtonProps,
+    "ColorButton"
+>(Gtk.ColorButton)
 export type ColorButton = ReturnType<typeof ColorButton>
 
 function MyWidget() {
-    function setup(button: ColorButton) {
-
-    }
+    function setup(button: ColorButton) {}
 
     return <ColorButton
         setup={setup}
         useAlpha
-        rgba={new Gdk.RGBA({
-            red: 1,
-            green: 0,
-            blue: 0,
-            alpha: 0.5,
-        })}
+        rgba={
+            new Gdk.RGBA({
+                red: 1,
+                green: 0,
+                blue: 0,
+                alpha: 0.5,
+            })
+        }
+        onColorSet={(self) => {
+            console.log(self.rgba)
+        }}
     />
 }
 ```
+
+:::note
+Signal properties have to be annotated manually for TypeScript.
+You can reference [Gtk3](https://gjs-docs.gnome.org/gtk30~3.0/)
+and [Astal](/astal/reference#classes) for available signals.
+:::

docs/src/content/docs/getting-started/installation.mdx

@@ -2,7 +2,7 @@
 title: Installation
 description: How to install Astal
 sidebar:
-  order: 1
+    order: 1
 ---
 
 import { Tabs, TabItem } from "@astrojs/starlight/components"
@@ -29,64 +29,75 @@ yay -S libastal-git
 
 ```bash
 yay -S libastal-meta
-```
-
-  </TabItem>
-  <TabItem label="AGS">
-
-```bash
-yay -S aylurs-gtk-shell-git
 ```
 
   </TabItem>
 </Tabs>
 
-## From Source
+## Bulding core from source
+
+1. Clone the repo
 
 ```bash
-git clone https://github.com/Aylur/Astal.git
-cd Astal
+git clone https://github.com/aylur/astal.git
+cd astal/core
 ```
 
+2. Install the following dependencies
+
 <Tabs>
   <TabItem label="Fedora">
 
 ```bash
-sudo dnf install meson
-
-meson setup --prefix /usr build
-meson install -C build
+sudo dnf install meson gcc valac gtk3-devel gtk-layer-shell-devel
 ```
 
   </TabItem>
   <TabItem label="Arch">
 
 ```bash
-sudo pacman -Syu meson
-
-arch-meson build
-meson install -C build
+sudo pacman -Syu meson vala gtk3 gtk-layer-shell gobject-introspection
 ```
 
   </TabItem>
   <TabItem label="Alpine">
 
 ```bash
-sudo apk add meson
-
-meson setup --prefix /usr build
-meson install -C build
+sudo apk add meson g++ vala gtk+3.0-dev gtk-layer-shell-dev gobject-introspection-dev
 ```
 
   </TabItem>
   <TabItem label="Ubuntu">
 
 ```bash
-sudo apt install meson
+sudo apt install meson valac libgtk3-dev libgtk-layer-shell-dev gobject-introspection
+```
 
-meson setup --prefix /usr build
-meson install -C build
+  </TabItem>
+  <TabItem label="openSUSE">
+
+```bash
+sudo zypper install gcc meson vala gtk3-devel gtk-layer-shell-devel gobject-introspection-devel
 ```
 
   </TabItem>
 </Tabs>
+
+3. Build and install with `meson`
+
+```bash
+meson setup build
+meson install -C build
+```
+
+:::note
+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, you set the `prefix` option:
+
+```bash
+meson setup --prefix /usr build
+meson install -C build
+```
+
+:::

docs/src/content/docs/getting-started/introduction.md

@@ -8,8 +8,8 @@ sidebar:
 ## What is Astal?
 
 Astal (_meaning "desk"_) is a bundle of libraries built using [GLib](https://docs.gtk.org/glib/) in Vala and C.
-The core library [libastal](/libastal) has some Gtk widgets that come packaged,
-the most important one is the [Window](/libastal/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell).
+The core library [libastal](/astal/reference) has some Gtk widgets that come packaged,
+the most important one is the [Window](/astal/reference/class.Window.html) which is the main toplevel component using [gtk-layer-shell](https://github.com/wmww/gtk-layer-shell).
 This is what allows us to use Gtk as shell components on Wayland.
 libastal also comes with some utility functions such as running external processes,
 reading, writing and monitoring files.

docs/src/content/docs/index.mdx

@@ -14,7 +14,7 @@ hero:
           icon: right-arrow
           variant: primary
         - text: Reference
-          link: /astal/reference/references
+          link: /astal/libraries/references
           icon: open-book
           variant: secondary
         - text: View on GitHub

docs/src/content/docs/libraries/references.md

@@ -0,0 +1,49 @@
+---
+title: References
+description: References of libraries
+sidebar:
+    order: 0
+---
+
+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](/reference): libastal the core library, which has the widgets and utilites
+- [Apps](/reference/apps): Library and cli tool for querying applications
+- [Auth](/reference/auth): Authentication library using PAM
+- [Battery](/reference/battery): DBus proxy library for upower daemon
+- [Bluetooth](/reference/bluetooth): Library to control bluez over dbus
+- [Hyprland](/reference/hyprland): Library and cli tool for Hyprland IPC socket
+- [Mpris](/reference/mpris): Library and cli tool for controlling media players
+- [Network](/reference/network): NetworkManager wrapper library
+- [Notifd](/reference/notifd): A notification daemon library and cli tool
+- [PowerProfiles](/reference/powerprofiles): Library and cli to control upowerd powerprofiles
+- [River](/reference/river): Library and cli tool for getting status information of the river wayland compositor
+- [Tray](/reference/tray): A systemtray library and cli tool
+- [WirePlumber](/reference/wireplumber): A library for audio control using wireplumber