From 6f39857dc7bf59d84c89b311690e858ce0a4724e Mon Sep 17 00:00:00 2001 From: Aylur Date: Tue, 3 Sep 2024 20:32:41 +0200 Subject: docs: migrate to vitepress vitepress feels a bit more polished and clean --- docs/src/assets/front-image.png | Bin 138489 -> 0 bytes docs/src/components/Showcase.astro | 37 -- docs/src/content/config.ts | 6 - docs/src/content/docs/ags/cli-app.md | 129 ------- docs/src/content/docs/ags/faq.md | 159 -------- docs/src/content/docs/ags/first-widgets.mdx | 429 --------------------- docs/src/content/docs/ags/theming.md | 113 ------ docs/src/content/docs/ags/utilities.md | 179 --------- docs/src/content/docs/ags/variable.md | 142 ------- docs/src/content/docs/ags/widget.md | 150 ------- .../content/docs/getting-started/installation.mdx | 103 ----- .../content/docs/getting-started/introduction.md | 28 -- docs/src/content/docs/getting-started/languages.md | 64 --- docs/src/content/docs/getting-started/nix.md | 8 - docs/src/content/docs/index.mdx | 67 ---- docs/src/content/docs/libraries/references.md | 49 --- docs/src/content/showcases.ts | 13 - docs/src/env.d.ts | 2 - docs/src/style.css | 72 ---- 19 files changed, 1750 deletions(-) delete mode 100644 docs/src/assets/front-image.png delete mode 100644 docs/src/components/Showcase.astro delete mode 100644 docs/src/content/config.ts delete mode 100644 docs/src/content/docs/ags/cli-app.md delete mode 100644 docs/src/content/docs/ags/faq.md delete mode 100644 docs/src/content/docs/ags/first-widgets.mdx delete mode 100644 docs/src/content/docs/ags/theming.md delete mode 100644 docs/src/content/docs/ags/utilities.md delete mode 100644 docs/src/content/docs/ags/variable.md delete mode 100644 docs/src/content/docs/ags/widget.md delete mode 100644 docs/src/content/docs/getting-started/installation.mdx delete mode 100644 docs/src/content/docs/getting-started/introduction.md delete mode 100644 docs/src/content/docs/getting-started/languages.md delete mode 100644 docs/src/content/docs/getting-started/nix.md delete mode 100644 docs/src/content/docs/index.mdx delete mode 100644 docs/src/content/docs/libraries/references.md delete mode 100644 docs/src/content/showcases.ts delete mode 100644 docs/src/env.d.ts delete mode 100644 docs/src/style.css (limited to 'docs/src') diff --git a/docs/src/assets/front-image.png b/docs/src/assets/front-image.png deleted file mode 100644 index 0fbfcca..0000000 Binary files a/docs/src/assets/front-image.png and /dev/null differ diff --git a/docs/src/components/Showcase.astro b/docs/src/components/Showcase.astro deleted file mode 100644 index 7eea178..0000000 --- a/docs/src/components/Showcase.astro +++ /dev/null @@ -1,37 +0,0 @@ ---- -interface Props { - src: string - author: string - url: string -} - -const { src, author, url } = Astro.props ---- - -
- - {author} - -
- Author: {author} -
-
- - diff --git a/docs/src/content/config.ts b/docs/src/content/config.ts deleted file mode 100644 index 45f60b0..0000000 --- a/docs/src/content/config.ts +++ /dev/null @@ -1,6 +0,0 @@ -import { defineCollection } from 'astro:content'; -import { docsSchema } from '@astrojs/starlight/schema'; - -export const collections = { - docs: defineCollection({ schema: docsSchema() }), -}; diff --git a/docs/src/content/docs/ags/cli-app.md b/docs/src/content/docs/ags/cli-app.md deleted file mode 100644 index 3365505..0000000 --- a/docs/src/content/docs/ags/cli-app.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: CLI and App -description: Reference of the singleton App instance -sidebar: - order: 3 ---- - -`App` is a singleton **instance** of [Astal.Application](/astal/reference/class.Application.html). - -```tsx -import { App } from "astal" -``` - -## Entry point - -```tsx -// app.ts -App.start({ - main() { - // setup anything - // instantiate widgets - }, -}) -``` - -:::caution -You can not instantiate widgets outside of the main function. -::: - -## Instance identifier - -You can run multiple instance by defining a unique instance name. - -```tsx -// app.ts -App.start({ - instanceName: "my-instance", // defaults to "astal" - main() {}, -}) -``` - -## Messaging from CLI - -If you want to interact with an instance from the cli, you can do so by sending a message. - -```ts -// app.ts -App.start({ - main() {}, - requestHandler(request: string, res: (response: any) => void) { - if (request == "say hi") { - res("hi cli") - } - res("unknown command") - }, -}) -``` - -```bash -# ags cli -$ ags -m "say hi" -hi cli - -# astal cli -$ astal say hi -hi cli -``` - -If you want to run arbitrary JavaScript from cli, you can use `App.eval`. -It will evaluate the passed string as the body of an `async` function. - -```ts -// app.ts -App.start({ - main() {}, - requestHandler(js: string, res) { - App.eval(js).then(res).catch(res) - }, -}) -``` - -If the string does not contain a semicolon, a single expression is assumed and returned implicity. - -```bash -$ ags -m "'hello'" -hello -``` - -If the string contains a semicolon, you have to return explicitly - -```bash -$ ags -m "'hello';" -undefined - -$ ags -m "return 'hello';" -hello -``` - -## App without AGS - -As mentioned before AGS is only a scaffolding tool. You can setup -a dev environment and a bundler yourself. In which case you won't be using -the ags cli to run the bundled scripts. The produced script can run as the main instance -and a "client" instance. - -The first time you run your bundled script the `main` function gets executed. -While that instance is running any subsequent execution of the script will call -the `client` function. - -```ts -// main.ts -App.start({ - // main instance - main(...args: Array) { - print(...args) - }, - - // every subsequent calls - client(message: (msg: string) => string, ...args: Array) { - const res = message("you can message the main instance") - console.log(res) - }, - - // this runs in the main instance - requestHandler(request: string, res: (response: any) => void) { - res("response from main") - }, -}) -``` diff --git a/docs/src/content/docs/ags/faq.md b/docs/src/content/docs/ags/faq.md deleted file mode 100644 index 5599fe3..0000000 --- a/docs/src/content/docs/ags/faq.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: FAQ -description: Frequently asked question, common issues, tips and tricks ---- - -## Monitor id does not match compositor - -The monitor property that windows expect is mapped by Gdk, which is not always -the same as the compositor. Instead use the `gdkmonitor` property which expects -a `Gdk.Monitor` object which you can get from compositor libraries. - -Example with Hyprland - -```js -import Hyprland from "gi://AstalHyprland" - -function Bar(gdkmonitor) { - return -} - -function main() { - for (const m of Hyprland.get_default().get_monitors()) { - Bar(m.gdk_monitor) - } -} - -App.start({ main }) -``` - -## Environment variables - -JavaScript is **not** an bash. - -```tsx -const HOME = exec("echo $HOME") // does not work -``` - -`exec` and `execAsync` runs the passed program as is, its **not** run in a -shell environment, so the above example just passes `$HOME` as a string literal -to the `echo` program. - -:::caution[Please don't do this] -You could pass it to bash, but that is a horrible approach. - -```tsx -const HOME = exec("bash -c 'echo $HOME'") -``` - -::: - -You can read environment variables with [GLib.getenv](https://gjs-docs.gnome.org/glib20~2.0/glib.getenv). - -```tsx -import GLib from "gi://GLib" - -const HOME = GLib.getenv("HOME") -``` - -## Custom svg symbolic icons - -Put the svgs in a directory, named `-symbolic.svg` -and use `App.add_icons` or `icons` parameter in `App.start` - -```js -// app.ts -App.start({ - icons: `${SRC}/icons`, - main() { - Widget.Icon({ - icon: "custom-symbolic", // custom-symbolic.svg - css: "color: green;", // can be colored, like other named icons - }) - }, -}) -``` - -:::note -If there is a name clash with an icon from your current icon pack -the icon pack will take precedence -::: - -## Logging - -The `console` API in gjs uses glib logging functions. -If you just want to print some text as is to stdout -use the globally available `print` function or `printerr` for stderr. - -```js -print("print this line to stdout") -printerr("print this line to stderr") -``` - -## Binding custom structures - -The `bind` function can take two types of objects. - -```typescript -interface Subscribable { - subscribe(callback: (value: T) => void): () => void - get(): T -} - -interface Connectable { - connect(signal: string, callback: (...args: any[]) => unknown): number - disconnect(id: number): void -} -``` - -`Connectable` is for mostly gobjects, while `Subscribable` is for `Variables` -and custom objects. - -For example you can compose `Variables` in using a class. - -```typescript -type MyVariableValue = { - number: number - string: string -} - -class MyVariable { - number = Variable(0) - string = Variable("") - - get(): MyVariableValue { - return { - number: this.number.get(), - string: this.string.get(), - } - } - - subscribe(callback: (v: MyVariableValue) => void) { - const unsub1 = this.number.subscribe((value) => { - callback({ string: value, number: this.number.get() }) - }) - - const unsub2 = this.string.subscribe((value) => { - callback({ number: value, string: this.string.get() }) - }) - - return () => { - unsub1() - unsub2() - } - } -} -``` - -Then it can be used with `bind`. - -```tsx -function MyWidget() { - const myvar = new MyVariableValue() - const label = bind(myvar).as(({ string, number }) => { - return `${string} ${number}` - }) - - return