docs: more doc improvements, setting up LuaLS addon

.vscode/settings.json

@@ -2,4 +2,5 @@
   "Lua.workspace.library": [
     "../hitokage-lua-lib/src/hitokage.lua"
   ],
+  "Lua.runtime.version": "Lua 5.4"
 }

README.md

@@ -5,7 +5,7 @@
 It is primarily built for usage with [ `komorebi` ](https://github.com/LGUG2Z/komorebi), but is also usable as a 
 standalone drop-in replacement for the default Windows Taskbar.
 
-Documentation and guides at: ~~nowhere LOL!~~ (🚧 TODO USER FACING DOCS 🚧)
+Documentation and guides at: codyduong.github.io/hitokage/
 
 ## Demos
 

docs/api/index.md

@@ -0,0 +1,10 @@
+# API
+
+!!! note inline end
+
+    Many API references are stubs or missing content due
+    to limitations of the LuaLS documentation generator. See [issue #54](https://github.com/codyduong/hitokage/issues/53)
+
+Lua API references for _hitokage_. They are autogenerated from [ `hitokage-lua-lib` ](https://github.com/codyduong/hitokage/tree/master/hitokage-lua-lib) using [Lua Language Server (LuaLS)](https://github.com/LuaLS/lua-language-server).
+
+It is recommended to setup using LuaLS to reference _hitokage_'s lua API, see [Setting up Lua Language Server](../configuration.html#setting-up-lua-language-server).

docs/configuration/index.md

@@ -0,0 +1,86 @@
+# Configuration
+
+*hitokage* is configured with lua and css[^1]. *hitokage* by default looks for your configuration in
+`%USERPROFILE%/.config/hitokage` and it looks for `init.lua` and `styles.css`.
+
+The minimal configuration might look something like this:
+
+`init.lua`
+```lua
+local monitors = hitokage.monitor.get_all()
+
+for _, monitor in ipairs(monitors) do
+  monitor:attach({
+    children = {
+      { Workspace = { halign = "Start", item_height = 24, item_width = 24 } },
+      { Box = {} },
+      { Clock = { format = "%a %b %u %r", halign = "End" } },
+    },
+  })
+end
+```
+
+`styles.css`
+```css
+.bar {
+  background-color: rgba(29, 32, 33, 0.0);
+  color: #f2e5bc;
+
+  font-family: 'MesloLGS NF', 'Courier New', 'Bars', 'Font Awesome 5 Free';
+  font-size: 12px;
+  line-height: 12px;
+  min-height: 24px;
+}
+
+.workspace {
+  padding: 0px 0px 0px 0px;
+  /* border: 1px solid rgba(255, 0, 0, 0.4); */
+}
+
+.workspacechild {
+  /* distance between workspace children */
+  /* margin-left: 8px; */
+  border: 1px solid rgba(168, 153, 132, 0.4);
+
+  color: #f2e5bc;
+  background-color: rgba(60, 56, 54, 0.4);
+
+  font-size: 11px;
+  /* border-radius: 11px; */
+
+  transition: all 500ms;
+  transition-property: min-width, background-color;
+}
+
+.workspacechild:first-child {
+  margin-left: 0px;
+}
+
+.workspacechild:selected {
+  /* min-width: 32px; */
+  border: 1px solid #f2e5bc;
+  background-color: #f2e5bc;
+  color: #333333;
+  font-weight: bold;
+}
+```
+
+[^1]: More details can be found here: [about/features](../features.html)
+
+## Setting up Lua Language Server
+
+!!! warning "🚧In progress🚧"
+
+    This feature is not matured. It will require a clone of the repository.
+
+_hitokage_ comes with type definitions for lua using [_lua-language-server_ (LuaLS)](https://luals.github.io/). It is located at [`hitokage-lua-lib`](https://github.com/codyduong/hitokage/tree/master/hitokage-lua-lib).
+
+Once installed, you can configure LuaLS to add the type annotations for _hitokage_. You can follow [LuaLS's Configuration Guide](https://luals.github.io/wiki/configuration/), or an abridged version for configuring the addition of _hitokage_'s type definitions is below:
+
+You will have to clone the entire repo, then point your `workspace.library` at `.\hitokage-lua-lib`
+
+!!! info "LuaLS addon system"
+
+    LuaLS comes with support for [addons](https://luals.github.io/wiki/addons/). Once _hitokage_ reaches v0.1.0 an addon will be published
+    that will be available through LuaLS's addon system for _hitokage_'s type definitions. This is
+    best suited for VSCode users who have installed the [sumneko.lua](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) addon.

docs/gen_pages.py

@@ -34,7 +34,7 @@ def replace_link(match: re.Match[str]) -> str:
 
             new_url = f"#{anchor}"
 
-            if ":" in anchor:
+            if anchor.count(':') == 1:
                 path, anchor = anchor.split(":")
                 new_url = f"./{path}.html#{anchor}"
 

examples/testbench/init.lua

@@ -1,6 +1,6 @@
 local monitors = hitokage.monitor.get_all()
 
---- @type BarArray
+---@type BarArray
 local bars = {}
 
 local reactive_labels = {}
@@ -21,7 +21,7 @@ local clock_icons = {
 	"\u{F1449}",
 }
 
---- @type table<number, ReactiveString>
+---@type table<number, ReactiveString>
 local reactive_clock_icons = {}
 
 for _, monitor in ipairs(monitors) do
@@ -185,16 +185,16 @@ for _, monitor in ipairs(monitors) do
 	::continue::
 end
 
---- @alias WorkspaceTable table<number, Workspace>
---- @type WorkspaceTable
+---@alias WorkspaceTable table<number, Workspace>
+---@type WorkspaceTable
 local workspaces = {}
 
---- @alias ClockTable table<number, Clock>
---- @type ClockTable
+---@alias ClockTable table<number, Clock>
+---@type ClockTable
 local clocks = {}
 
---- @alias BoxesTable table<number, Box>
---- @type BoxesTable
+---@alias BoxesTable table<number, Box>
+---@type BoxesTable
 local boxes = {}
 
 for i, bar in ipairs(bars) do
@@ -216,7 +216,7 @@ for i, bar in ipairs(bars) do
 	end
 
 	local label = bar:get_child_by_id("test1", true)
-	--- @cast label Label
+	---@cast label Label
 	local routine = hitokage.timeout(1000, function()
 		local current_label = label:get_label()
 		if current_label == "\u{F4BC}" then

hitokage-lua-lib/config.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://raw.githubusercontent.com/LuaLS/LLS-Addons/main/schemas/addon_config.schema.json",
+  "words": ["hitokage"],
+  "files": ["init.lua"],
+  "settings": {
+    "Lua.runtime.version": "Lua 5.4"
+  }
+}

hitokage-lua-lib/library/api/bar.lua

@@ -0,0 +1,36 @@
+---@meta hitokage.api.bar
+
+-------------------------------------------------------------------------------
+---Represents the bar module
+---@class barlib
+local bar = {}
+
+---!!! danger "Deprecated"
+---
+---    Use [`monitor:attach`](lua://Monitor.attach) instead.
+---
+---Creates a new bar on a specified monitor.
+---
+---!!! example
+---
+---    ```lua
+---    local monitors = hitokage.monitor.get_all()
+---    
+---    for _, monitor in ipairs(monitors) do
+---      hitokage.bar.create(monitor, {
+---        children = {
+---          { Box = {} },
+---          { Workspace = { halign = "Center", item_height = 22, item_width = 22 } },
+---          { Clock = { format = "%a %b %u %r", halign = 'End' } },
+---        },
+---      })
+---    end
+---    ```
+---
+---@deprecated
+---@param monitor Monitor
+---@param bar_props BarProps
+---@return Bar
+function bar.create(monitor, bar_props) end
+
+return bar

hitokage-lua-lib/library/api/monitor.lua

@@ -0,0 +1,72 @@
+---@meta hitokage.api.monitor
+
+-------------------------------------------------------------------------------
+---Represents the monitor module
+---@class monitorlib
+local monitor = {}
+
+---@return MonitorVec
+function monitor.get_all() end
+
+---@return Monitor
+function monitor.get_primary() end
+
+-------------------------------------------------------------------------------
+---Links to 'pub struct MonitorGeometry' in 'hitokage-core\src\lua\monitor.rs'
+---@class MonitorGeometry
+---@field x number
+---@field y number
+---@field width number
+---@field height number
+
+-------------------------------------------------------------------------------
+---Links to 'pub struct MonitorScaleFactor' in 'hitokage-core\src\lua\monitor.rs'
+---@class MonitorScaleFactor
+---@field x number,
+---@field y number,
+
+-------------------------------------------------------------------------------
+---Links to 'pub struct Monitor' in 'hitokage-core\src\lua\monitor.rs'
+---@class Monitor
+---@field connector string | nil,
+---@field description string | nil,
+---@field geometry MonitorGeometry,
+---@field manufacturer string | nil,
+---@field model string | nil,
+---This value is in millihertz (mHz) not hertz (Hz)
+---@field refresh_rate number,
+---@field is_primary boolean,
+---@field device string,
+---@field device_id string,
+---@field id number,
+---@field name string,
+---@field scale_factor MonitorScaleFactor,
+local monitor_instance = {}
+
+---@alias MonitorVec table<number, Monitor>
+
+---Attaches a component on the monitor.
+---
+---!!! example
+---
+---    ```lua
+---    local monitors = hitokage.monitor.get_all()
+---    
+---    for _, monitor in ipairs(monitors) do
+---      monitor:attach({
+---        children = {
+---          { Box = {} },
+---          { Workspace = { halign = "Center", item_height = 22, item_width = 22 } },
+---          { Clock = { format = "%a %b %u %r", halign = 'End' } },
+---        },
+---      })
+---    end
+---    ```
+---
+---@param props BarProps
+---@return Bar
+function monitor_instance:attach(props) end
+
+-------------------------------------------------------------------------------
+
+return monitor

hitokage-lua-lib/library/api/reactive.lua

@@ -0,0 +1,47 @@
+---@meta hitokage.api.reactive
+
+-------------------------------------------------------------------------------
+---Represents the monitor module for String type
+---@class ReactiveString
+---@field value string
+local reactive_string_userdata = {}
+
+---Get the value of the reactive variable
+---@return string
+function reactive_string_userdata:get() end
+
+---Set the value of the reactive variable
+---@param value string
+---@return nil
+function reactive_string_userdata:set(value) end
+
+-------------------------------------------------------------------------------
+-- ---Represents the monitor module for Bool type
+-- ---@class ReactiveBool
+-- local reactive_bool_userdata = {}
+
+-- ---Get the value of the reactive variable
+-- ---@return boolean
+-- function reactive_bool_userdata:get() end
+
+-- ---Set the value of the reactive variable
+-- ---@param value boolean
+-- ---@return nil
+-- function reactive_bool_userdata:set(value) end
+
+-------------------------------------------------------------------------------
+---Represents the reactive module
+---@class reactivelib
+local reactive = {}
+
+---Creates a pointer to an rust Arc<Mutex<T>>. Currently only supports strings.
+---
+---@param value string
+---@return ReactiveString
+function reactive.create(value) end
+
+-- ---@param value boolean
+-- ---@return ReactiveBool
+-- function reactive.create(value) end
+
+return reactive

hitokage-lua-lib/library/common.lua

@@ -0,0 +1,7 @@
+---@meta hitokage.common
+
+---Links to Align in 'hitokage-core\src\common.rs'
+---@alias Align 'Fill' | 'Start' | 'End' | 'Center' | 'Baseline' | UnknownAlign
+
+---@class UnknownAlign
+---@field __Unknown number