From b3c072734afcc4eeb2961a085cb74d6adb085d34 Mon Sep 17 00:00:00 2001 From: Ottatop Date: Sun, 23 Jul 2023 15:25:11 -0500 Subject: [PATCH] Move all examples to Usage section --- .github/workflows/ldoc.yml | 5 ++ api/lua/doc/config.ld | 2 +- api/lua/doc/index.html | 180 ------------------------------------- api/lua/doc/ldoc.css | 37 ++++---- api/lua/doc/output.lua | 6 +- api/lua/doc/tag.lua | 84 ++++++++--------- api/lua/doc/window.lua | 170 +++++++++++++++++------------------ 7 files changed, 154 insertions(+), 330 deletions(-) delete mode 100644 api/lua/doc/index.html diff --git a/.github/workflows/ldoc.yml b/.github/workflows/ldoc.yml index 05808f7..26efe14 100644 --- a/.github/workflows/ldoc.yml +++ b/.github/workflows/ldoc.yml @@ -9,6 +9,10 @@ on: push: branches: - main + +env: + BRANCH_NAME: ${{ github.head_ref || github.ref_name }} + jobs: build: name: Build docs @@ -32,3 +36,4 @@ jobs: with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./api/lua/doc/doc + destination_dir: $BRANCH_NAME diff --git a/api/lua/doc/config.ld b/api/lua/doc/config.ld index cb91c46..c8d4c76 100644 --- a/api/lua/doc/config.ld +++ b/api/lua/doc/config.ld @@ -4,4 +4,4 @@ description = "A very, VERY WIP Smithay-based Wayland compositor" boilerplate = true multimodule = true no_space_before_args = true -style = true +style = true -- Use the ldoc.css in the current dir diff --git a/api/lua/doc/index.html b/api/lua/doc/index.html deleted file mode 100644 index cc7e8e0..0000000 --- a/api/lua/doc/index.html +++ /dev/null @@ -1,180 +0,0 @@ - - - - - Reference - - - - -
- -
- -
-
-
- - -
- - - - - - -
- -

Module ProcessModule

-

- -

-

- -

- - -

Functions

- - - - - - - - - -
process_module.spawn (command, callback)Spawn a process with an optional callback for its stdout, stderr, and exit information.
process_module.spawn_once (command, callback)Spawn a process only if it isn't already running, with an optional callback for its stdout, stderr, and exit information.
-

Fields

- - - - - -
args - -
- -
-
- - -

Functions

- -
-
- - process_module.spawn (command, callback) -
-
- Spawn a process with an optional callback for its stdout, stderr, and exit information.

- -

callback has the following parameters: - - stdout - The process's stdout printed this line. - - stderr - The process's stderr printed this line. - - exit_code - The process exited with this code. - - exit_msg - The process exited with this message. - - -

Parameters:

-
    -
  • command - string|string[] The command as one whole string or a table of each of its arguments -
    • -
  • callback - fun(stdout: string|nil, stderr: string|nil, exitcode: integer|nil, exitmsg: string|nil)? A callback to do something whenever the process's stdout or stderr print a line, or when the process exits. -
    • -
- - - - - -
-
- - process_module.spawn_once (command, callback) -
-
- Spawn a process only if it isn't already running, with an optional callback for its stdout, stderr, and exit information.

- -

callback has the following parameters: - - stdout: The process's stdout printed this line. - - stderr: The process's stderr printed this line. - - exit_code: The process exited with this code. - - exit_msg: The process exited with this message.

- -

spawn_once checks for the process using pgrep. If your system doesn't have pgrep, this won't work properly. - - -

Parameters:

-
    -
  • command - string|string[] The command as one whole string or a table of each of its arguments -
    • -
  • callback - fun(stdout: string|nil, stderr: string|nil, exitcode: integer|nil, exitmsg: string|nil)? A callback to do something whenever the process's stdout or stderr print a line, or when the process exits. -
    • -
- - - - - -
-
-

Fields

- -
-
- - args -
-
- - - - - -
    -
  • args - Args -
    • -
- - - - - -
-
- - -
-
-
-generated by LDoc 1.5.0 -Last updated 2023-07-22 11:35:14 -
-
- - diff --git a/api/lua/doc/ldoc.css b/api/lua/doc/ldoc.css index 3088cbb..ca2e320 100644 --- a/api/lua/doc/ldoc.css +++ b/api/lua/doc/ldoc.css @@ -70,8 +70,8 @@ body { /* Body of window (makes it look like sidebars) */ background-color: #202020; margin: 0px; } -code, tt { font-family: "JetBrains Mono", monospace; font-size: 1em; } -span.parameter { font-family: "JetBrains Mono", monospace; } +code, tt { font-family: "JetBrains Mono", "Consolas", monospace; font-size: 1em; } +span.parameter { font-family: "JetBrains Mono", "Consolas", monospace; } span.parameter:after { content:":"; } span.types:before { content:"("; } span.types:after { content:")"; } @@ -122,8 +122,8 @@ pre { font-family: "JetBrains Mono", "Andale Mono", monospace; } -pre.example { - font-size: .85em; +pre.example { /* Usage blocks */ + font-size: 1em; } table.index { border: 1px #00007f; } @@ -297,24 +297,23 @@ ul ol { margin-top: 0px; } /* make the target distinct; helps when we're navigating to a function */ a:target + * { - background-color: #FF9; + background-color: #535353; } - /* styles for prettification of source */ -pre .comment { color: #558817; } -pre .constant { color: #a8660d; } -pre .escape { color: #844631; } -pre .keyword { color: #aa5050; font-weight: bold; } -pre .library { color: #0e7c6b; } +pre .comment { color: #9e9fa0; } +pre .constant { color: #5ae0df; } +pre .escape { color: #2dc7c4; } +pre .keyword { color: #be95ff; font-weight: bold; } +pre .library { color: #ee5396; } pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; } -pre .string { color: #8080ff; } -pre .number { color: #f8660d; } -pre .function-name { color: #60447f; } -pre .operator { color: #2239a8; font-weight: bold; } -pre .preprocessor, pre .prepro { color: #a33243; } -pre .global { color: #800080; } -pre .user-keyword { color: #800080; } +pre .string { color: #25be6a; } +pre .number { color: #3ddbd9; } +pre .function-name { color: #8cb6ff; } +pre .operator { color: #b6b8bb; font-weight: bold; } +pre .preprocessor, pre .prepro { color: #ff91c1; } +pre .global { color: #ee5396; } +pre .user-keyword { color: #ee5396; } pre .prompt { color: #558817; } -pre .url { color: #272fc2; text-decoration: underline; } +pre .url { color: #5ae0df; text-decoration: underline; } diff --git a/api/lua/doc/output.lua b/api/lua/doc/output.lua index 44afe99..86b8f63 100644 --- a/api/lua/doc/output.lua +++ b/api/lua/doc/output.lua @@ -14,9 +14,9 @@ local output_module = {} ---rather, "name" is the name of the connector the output is connected to. ---This should be something like "HDMI-A-0", "eDP-1", or similar. --- ----### Example ---- local monitor = output.get_by_name("DP-1") ---- print(monitor.name) -- should print `DP-1` +---@usage +---local monitor = output.get_by_name("DP-1") +---print(monitor.name) -- should print `DP-1` ---@tparam string name The name of the output. ---@treturn Output|nil output The output, or nil if none have the provided name. function output_module.get_by_name(name) end diff --git a/api/lua/doc/tag.lua b/api/lua/doc/tag.lua index 0bd1239..546a3c9 100644 --- a/api/lua/doc/tag.lua +++ b/api/lua/doc/tag.lua @@ -19,14 +19,14 @@ local tag_module = {} ---Add tags to the specified output. --- ----### Examples ---- local op = output.get_by_name("DP-1") ---- if op ~= nil then ---- tag.add(op, "1", "2", "3", "4", "5") -- Add tags with names 1-5 ---- end ----You can also pass in a table. ---- local tags = {"Terminal", "Browser", "Code", "Potato", "Email"} ---- tag.add(op, tags) -- Add tags with those names +---@usage +---local op = output.get_by_name("DP-1") +---if op ~= nil then +--- tag.add(op, "1", "2", "3", "4", "5") -- Add tags with names 1-5 +---end +--- -- You can also pass in a table. +---local tags = {"Terminal", "Browser", "Code", "Potato", "Email"} +---tag.add(op, tags) -- Add tags with those names ---@tparam Output output The output you want these tags to be added to. ---@tparam string ... The names of the new tags you want to add. ---@see Output.add_tags @@ -34,12 +34,12 @@ function tag_module.add(output, ...) end ---Toggle a tag on the specified output. If `output` isn't specified, toggle it on the currently focused output instead. --- ----### Example ---- -- Assuming all tags are toggled off... ---- local op = output.get_by_name("DP-1") ---- tag.toggle("1", op) ---- tag.toggle("2", op) ---- -- will cause windows on both tags 1 and 2 to be displayed at the same time. +---@usage +--- -- Assuming all tags are toggled off... +---local op = output.get_by_name("DP-1") +---tag.toggle("1", op) +---tag.toggle("2", op) +--- -- will cause windows on both tags 1 and 2 to be displayed at the same time. ---@tparam string name The name of the tag. ---@tparam ?Output output The output. ---@see Tag.toggle @@ -51,9 +51,9 @@ function tag_module.toggle(name, output) end --- ---This is used to replicate what a traditional workspace is on some other Wayland compositors. --- ----### Examples ---- -- Switches to and displays *only* windows on tag `3` on the focused output. ---- tag.switch_to("3") +---@usage +--- -- Switches to and displays *only* windows on tag `3` on the focused output. +---tag.switch_to("3") ---@tparam string name The name of the tag. ---@tparam ?Output output The output. ---@see Tag.switch_to @@ -62,13 +62,13 @@ function tag_module.switch_to(name, output) end ---Set a layout for the tag on the specified output. If no output is provided, set it for the tag on the currently focused one. ---Alternatively, provide a tag object instead of a name and output. --- ----### Examples ---- -- Set tag `1` on `DP-1` to the `Dwindle` layout ---- tag.set_layout("1", "Dwindle", output.get_by_name("DP-1")) +---@usage +--- -- Set tag `1` on `DP-1` to the `Dwindle` layout +--- tag.set_layout("1", "Dwindle", output.get_by_name("DP-1")) --- ---- -- Do the same as above. Note: if you have more than one tag named `1` then this picks the first one. ---- local t = tag.get_by_name("1")[1] ---- tag.set_layout(t, "Dwindle") +--- -- Do the same as above. Note: if you have more than one tag named `1` then this picks the first one. +---local t = tag.get_by_name("1")[1] +---tag.set_layout(t, "Dwindle") ---@tparam string name The name of the tag. ---@tparam Layout layout The layout. ---@tparam ?Output output The output. @@ -77,11 +77,11 @@ function tag_module.set_layout(name, layout, output) end ---Get all tags on the specified output. --- ----### Example ---- local op = output.get_focused() ---- if op ~= nil then ---- local tags = tag.get_on_output(op) -- All tags on the focused output ---- end +---@usage +---local op = output.get_focused() +---if op ~= nil then +--- local tags = tag.get_on_output(op) -- All tags on the focused output +---end ---@tparam Output output ---@treturn Tag[] ---@see Output.tags @@ -89,31 +89,31 @@ function tag_module.get_on_output(output) end ---Get all tags with this name across all outputs. --- ----### Example ---- -- Given one monitor with the tags "OBS", "OBS", "VSCode", and "Spotify"... ---- local tags = tag.get_by_name("OBS") ---- -- ...will have 2 tags in `tags`, while... ---- local no_tags = tag.get_by_name("Firefox") ---- -- ...will have `no_tags` be empty. +---@usage +--- -- Given one monitor with the tags "OBS", "OBS", "VSCode", and "Spotify"... +---local tags = tag.get_by_name("OBS") +--- -- ...will have 2 tags in `tags`, while... +---local no_tags = tag.get_by_name("Firefox") +--- -- ...will have `no_tags` be empty. ---@tparam string name The name of the tag(s) you want. ---@treturn Tag[] function tag_module.get_by_name(name) end ---Get all tags across all outputs. --- ----### Example ---- -- With two monitors with the same tags: "1", "2", "3", "4", and "5"... ---- local tags = tag.get_all() ---- -- ...`tags` should have 10 tags, with 5 pairs of those names across both outputs. +---@usage +--- -- With two monitors with the same tags: "1", "2", "3", "4", and "5"... +---local tags = tag.get_all() +--- -- ...`tags` should have 10 tags, with 5 pairs of those names across both outputs. ---@treturn Tag[] function tag_module.get_all() end ---Get the specified tag's name. --- ----### Example ---- -- Assuming the tag `Terminal` exists... ---- print(tag.name(tag.get_by_name("Terminal")[1])) ---- -- ...should print `Terminal`. +---@usage +--- -- Assuming the tag `Terminal` exists... +---print(tag.name(tag.get_by_name("Terminal")[1])) +--- -- ...should print `Terminal`. ---@tparam Tag t ---@treturn string|nil ---@see Tag.name diff --git a/api/lua/doc/window.lua b/api/lua/doc/window.lua index 9f43427..0ab6c55 100644 --- a/api/lua/doc/window.lua +++ b/api/lua/doc/window.lua @@ -44,13 +44,13 @@ function window_module.move_to_tag(w, name, output) end ---Set the specified window's size. --- ----### Examples +---@usage ---local win = window.get_focused() ---- if win ~= nil then ---- window.set_size(win, { w = 500, h = 500 }) -- make the window square and 500 pixels wide/tall ---- window.set_size(win, { h = 300 }) -- keep the window's width but make it 300 pixels tall ---- window.set_size(win, {}) -- do absolutely nothing useful ---- end +---if win ~= nil then +--- window.set_size(win, { w = 500, h = 500 }) -- make the window square and 500 pixels wide/tall +--- window.set_size(win, { h = 300 }) -- keep the window's width but make it 300 pixels tall +--- window.set_size(win, {}) -- do absolutely nothing useful +---end ---@tparam Window win ---@tparam table size A table of the form { w: integer?, h: integer? } ---@see Window.set_size @@ -61,11 +61,11 @@ function window_module.set_size(win, size) end ---This only sends a close *event* to the window and is the same as just clicking the X button in the titlebar. ---This will trigger save prompts in applications like GIMP. --- ----### Example ---- local win = window.get_focused() ---- if win ~= nil then ---- window.close(win) -- close the currently focused window ---- end +---@usage +---local win = window.get_focused() +---if win ~= nil then +--- window.close(win) -- close the currently focused window +---end ---@tparam Window win ---@see Window.close function window_module.close(win) end @@ -77,10 +77,10 @@ function window_module.toggle_floating(win) end ---Get the specified window's size. --- ----### Example ---- -- With a 4K monitor, given a focused fullscreen window `win`... ---- local size = window.size(win) ---- -- ...should have size equal to `{ w = 3840, h = 2160 }`. +---@usage +--- -- With a 4K monitor, given a focused fullscreen window `win`... +---local size = window.size(win) +--- -- ...should have size equal to `{ w = 3840, h = 2160 }`. ---@tparam Window win ---@treturn table|nil size The size of the window in the form { w: integer, h: integer }, or nil if it doesn't exist. ---@see Window.size @@ -92,11 +92,11 @@ function window_module.size(win) end ---The top left of the sheet if you trim it down is (0, 0). ---The location of this window is relative to that point. --- ----### Example ---- -- With two 1080p monitors side by side and set up as such, ---- -- if a window `win` is fullscreen on the right one... ---- local loc = window.loc(win) ---- -- ...should have loc equal to `{ x = 1920, y = 0 }`. +---@usage +--- -- With two 1080p monitors side by side and set up as such, +--- -- if a window `win` is fullscreen on the right one... +---local loc = window.loc(win) +--- -- ...should have loc equal to `{ x = 1920, y = 0 }`. ---@tparam Window win ---@treturn table|nil loc The location of the window in the form { x: integer, y: integer }, or nil if it's not on-screen or alive. ---@see Window.loc @@ -104,13 +104,13 @@ function window_module.loc(win) end ---Get the specified window's class. This is usually the name of the application. --- ----### Example ---- -- With Alacritty focused... ---- local win = window.get_focused() ---- if win ~= nil then ---- print(window.class(win)) ---- end ---- -- ...should print "Alacritty". +---@usage +--- -- With Alacritty focused... +---local win = window.get_focused() +---if win ~= nil then +--- print(window.class(win)) +---end +--- -- ...should print "Alacritty". ---@tparam Window win ---@treturn string|nil class This window's class, or nil if it doesn't exist. ---@see Window.class @@ -118,13 +118,13 @@ function window_module.class(win) end ---Get the specified window's title. --- ----### Example ---- -- With Alacritty focused... ---- local win = window.get_focused() ---- if win ~= nil then ---- print(window.title(win)) ---- end ---- -- ...should print the directory Alacritty is in or what it's running (what's in its title bar). +---@usage +--- -- With Alacritty focused... +---local win = window.get_focused() +---if win ~= nil then +--- print(window.title(win)) +---end +--- -- ...should print the directory Alacritty is in or what it's running (what's in its title bar). ---@tparam Window win ---@treturn string|nil title This window's title, or nil if it doesn't exist. ---@see Window.title @@ -132,13 +132,13 @@ function window_module.title(win) end ---Get this window's floating status. --- ----### Example ---- -- With the focused window floating... ---- local win = window.get_focused() ---- if win ~= nil then ---- print(window.floating(win)) ---- end ---- -- ...should print `true`. +---@usage +--- -- With the focused window floating... +---local win = window.get_focused() +---if win ~= nil then +--- print(window.floating(win)) +---end +--- -- ...should print `true`. ---@tparam Window win ---@treturn boolean|nil floating `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist. ---@see Window.floating @@ -146,11 +146,11 @@ function window_module.floating(win) end ---Get whether or not this window is focused. --- ----### Example ---- local win = window.get_focused() ---- if win ~= nil then ---- print(window.focused(win)) -- Should print `true` ---- end +---@usage +---local win = window.get_focused() +---if win ~= nil then +--- print(window.focused(win)) -- Should print `true` +---end ---@tparam Window win ---@treturn boolean|nil floating `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist. ---@see Window.focused @@ -164,20 +164,20 @@ local window = {} ---Set this window's size. --- ----### Examples ---- window.get_focused():set_size({ w = 500, h = 500 }) -- make the window square and 500 pixels wide/tall ---- window.get_focused():set_size({ h = 300 }) -- keep the window's width but make it 300 pixels tall ---- window.get_focused():set_size({}) -- do absolutely nothing useful +---@usage +---window.get_focused():set_size({ w = 500, h = 500 }) -- make the window square and 500 pixels wide/tall +---window.get_focused():set_size({ h = 300 }) -- keep the window's width but make it 300 pixels tall +---window.get_focused():set_size({}) -- do absolutely nothing useful ---@tparam table size A table of the form { `w`: `integer?`, `h`: `integer?` } ---@see WindowModule.set_size function window:set_size(size) end ---Move this window to a tag, removing all other ones. --- ----### Example ---- -- With the focused window on tags 1, 2, 3, and 4... ---- window.get_focused():move_to_tag("5") ---- -- ...will make the window only appear on tag 5. +---@usage +--- -- With the focused window on tags 1, 2, 3, and 4... +---window.get_focused():move_to_tag("5") +--- -- ...will make the window only appear on tag 5. ---@tparam string name ---@tparam ?Output output ---@see WindowModule.move_to_tag @@ -187,10 +187,10 @@ function window:move_to_tag(name, output) end --- ---Note: toggling off all tags currently makes a window not response to layouting. --- ----### Example ---- -- With the focused window only on tag 1... ---- window.get_focused():toggle_tag("2") ---- -- ...will also make the window appear on tag 2. +---@usage +--- -- With the focused window only on tag 1... +---window.get_focused():toggle_tag("2") +--- -- ...will also make the window appear on tag 2. ---@tparam string name ---@tparam ?Output output ---@see WindowModule.toggle_tag @@ -201,24 +201,24 @@ function window:toggle_tag(name, output) end ---This only sends a close *event* to the window and is the same as just clicking the X button in the titlebar. ---This will trigger save prompts in applications like GIMP. --- ----### Example ---- window.get_focused():close() -- close the currently focused window +---@usage +---window.get_focused():close() -- close the currently focused window ---@see WindowModule.close function window:close() end ---Toggle this window's floating status. --- ----### Example ---- window.get_focused():toggle_floating() -- toggles the focused window between tiled and floating +---@usage +---window.get_focused():toggle_floating() -- toggles the focused window between tiled and floating ---@see WindowModule.toggle_floating function window:toggle_floating() end ---Get this window's size. --- ----### Example ---- -- With a 4K monitor, given a focused fullscreen window... ---- local size = window.get_focused():size() ---- -- ...should have size equal to `{ w = 3840, h = 2160 }`. +---@usage +--- -- With a 4K monitor, given a focused fullscreen window... +---local size = window.get_focused():size() +--- -- ...should have size equal to `{ w = 3840, h = 2160 }`. ---@treturn table|nil size The size of the window in the form { `w`: `integer`, `h`: `integer` }, or nil if it doesn't exist. ---@see WindowModule.size function window:size() end @@ -229,49 +229,49 @@ function window:size() end ---The top left of the sheet if you trim it down is (0, 0). ---The location of this window is relative to that point. --- ----### Example ---- -- With two 1080p monitors side by side and set up as such, ---- -- if a window is fullscreen on the right one... ---- local loc = that_window:loc() ---- -- ...should have loc equal to `{ x = 1920, y = 0 }`. +---@usage +--- -- With two 1080p monitors side by side and set up as such, +--- -- if a window is fullscreen on the right one... +---local loc = that_window:loc() +--- -- ...should have loc equal to `{ x = 1920, y = 0 }`. ---@treturn table|nil loc The location of the window in the form { `x`: `integer`, `y`: `integer` }, or nil if it's not on-screen or alive. ---@see WindowModule.loc function window:loc() end ---Get this window's class. This is usually the name of the application. --- ----### Example ---- -- With Alacritty focused... ---- print(window.get_focused():class()) ---- -- ...should print "Alacritty". +---@usage +--- -- With Alacritty focused... +---print(window.get_focused():class()) +--- -- ...should print "Alacritty". ---@treturn string|nil class This window's class, or nil if it doesn't exist. ---@see WindowModule.class function window:class() end ---Get this window's title. --- ----### Example ---- -- With Alacritty focused... ---- print(window.get_focused():title()) ---- -- ...should print the directory Alacritty is in or what it's running (what's in its title bar). +---@usage +--- -- With Alacritty focused... +---print(window.get_focused():title()) +--- -- ...should print the directory Alacritty is in or what it's running (what's in its title bar). ---@treturn string|nil title This window's title, or nil if it doesn't exist. ---@see WindowModule.title function window:title() end ---Get this window's floating status. --- ----### Example ---- -- With the focused window floating... ---- print(window.get_focused():floating()) ---- -- ...should print `true`. +---@usage +--- -- With the focused window floating... +---print(window.get_focused():floating()) +--- -- ...should print `true`. ---@treturn boolean|nil floating `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist. ---@see WindowModule.floating function window:floating() end ---Get whether or not this window is focused. --- ----### Example ---- print(window.get_focused():focused()) -- should print `true`. +---@usage +---print(window.get_focused():focused()) -- should print `true`. ---@treturn boolean|nil floating `true` if it's floating, `false` if it's tiled, or nil if it doesn't exist. ---@see WindowModule.focused function window:focused() end