ci: fix branch name

GitHub Actions to build and deploy doc to gh-pages.

.cspell.json

@@ -0,0 +1,18 @@
+{
+  "words": [
+    "Aire-One",
+    "capi",
+    "constructorfct",
+    "fatalwarnings",
+    "fullscreen",
+    "hasitem",
+    "JohnnyMorganz",
+    "ldoc",
+    "luacheck",
+    "luadoc",
+    "lunarmodules",
+    "mousebindings",
+    "staticfct",
+    "stylua"
+  ]
+}

.editorconfig

@@ -5,8 +5,11 @@ root = true
 
 [*]
 indent_style = space
-indent_size = 4
+indent_size = 3
 end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
 insert_final_newline = true
+
+[*.{json,yaml}]
+indent_size = 2

.github/workflows/doc.yaml

@@ -0,0 +1,38 @@
+name: Build doc
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: lunarmodules/ldoc@v1.5.0
+      - uses: actions/upload-pages-artifact@v3
+        id: deployment
+        with:
+          path: doc/
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

.github/workflows/lint.yaml

@@ -0,0 +1,43 @@
+name: Lint
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  luacheck:
+    needs: []
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: lunarmodules/luacheck@v1
+
+  stylua:
+    needs: []
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: JohnnyMorganz/stylua-action@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          version: v0.20.0
+          args: --check .
+
+  ldoc:
+    needs: []
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: lunarmodules/ldoc@v1.5.0
+        with:
+          args: --fatalwarnings .
+
+  spellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: streetsidesoftware/cspell-action@v6
+        with:
+          incremental_files_only: false

.gitignore

@@ -1 +1 @@
-doc/
+/doc

.luacheckrc

@@ -1,34 +1,33 @@
--- Only allow symbols available in all Lua versions
 std = "min"
 
-files[".luacheckrc"].ignore = { "111", "112", "131" }
-files["config.ld"].ignore = { "111", "113" }
+cache = true
+
+include_files = {
+   ".luacheckrc",
+   "*.rockspec",
+   "src/",
+   "config.ld",
+}
 
--- Global objects defined by the C code
 read_globals = {
-    "awesome",
-    "button",
-    "dbus",
-    "drawable",
-    "drawin",
-    "key",
-    "keygrabber",
-    "mousegrabber",
-    "selection",
-    "tag",
-    "window",
-    "table.unpack",
-    "math.atan2",
+   "awesome",
+   "button",
+   "dbus",
+   "drawable",
+   "drawin",
+   "key",
+   "keygrabber",
+   "mousegrabber",
+   "selection",
+   "tag",
+   "window",
+   "table.unpack",
+   "math.atan2",
 }
 
 globals = {
-    "screen",
-    "mouse",
-    "root",
-    "client",
+   "screen",
+   "mouse",
+   "root",
+   "client",
 }
-
--- Enable cache (uses .luacheckcache relative to this rc file).
-cache = true
-
--- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

.stylua.toml

@@ -0,0 +1,6 @@
+indent_type = "Spaces"
+indent_width = 3
+call_parentheses = "None"
+
+[sort_requires]
+enabled = true

.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+  "Lua.runtime.path": [
+    "/usr/share/awesome/lib/?.lua",
+    "/usr/share/awesome/lib/?/init.lua"
+  ],
+  "[lua]": {
+    "editor.defaultFormatter": "JohnnyMorganz.stylua"
+  },
+  "stylua.targetReleaseVersion": "latest",
+  "files.associations": {
+    ".luacheckrc": "lua",
+    "*.rockspec": "lua",
+    "config.ld": "lua"
+  }
+}

README.md

@@ -4,3 +4,18 @@ A declarative API to connect signals for the AwesomeWM.
 
 It completes the native `gears.signal` module to make signal connection easier
 to manage.
+
+## Documentation
+
+API references for the latest release are available at <https://aire-one.github.io/awesome-slot/index.html>.
+
+It is also possible to manually build the documentation locally using ldoc. The
+documentation content is part of the source code, and all configurations needed
+are provided by the `config.ld` file. To generate documentation, you need to
+run :
+
+```sh
+ldoc .
+```
+
+The documentation site will be generated in the `doc` directory.

awesome-slot-dev-1.rockspec

@@ -0,0 +1,25 @@
+package = "awesome-slot"
+version = "dev-1"
+source = {
+   url = "git+https://github.com/Aire-One/awesome-slot.git",
+}
+description = {
+   summary = "A declarative API to connect signals for the AwesomeWM.",
+   detailed = "A declarative API to connect signals for the AwesomeWM.",
+   homepage = "https://github.com/Aire-One/awesome-slot",
+   license = "*** please specify a license ***",
+}
+build = {
+   type = "builtin",
+   modules = {
+      ["awesome-slot.init"] = "src/awesome-slot/init.lua",
+      ["awesome-slot.slots.client"] = "src/awesome-slot/slots/client.lua",
+      ["awesome-slot.slots.init"] = "src/awesome-slot/slots/init.lua",
+      ["awesome-slot.slots.ruled"] = "src/awesome-slot/slots/ruled.lua",
+      ["awesome-slot.slots.screen"] = "src/awesome-slot/slots/screen.lua",
+      ["awesome-slot.slots.tag"] = "src/awesome-slot/slots/tag.lua",
+   },
+   copy_directories = {
+      "doc",
+   },
+}

config.ld

@@ -14,10 +14,10 @@ sort_modules = true
 not_luadoc = true
 
 file = {
-    "init.lua",
-    exclude = {
-        "slots",
-    },
+   "src/awesome-slot",
+   exclude = {
+      "src/awesome-slot/slots",
+   },
 }
 
 -- Define some new ldoc tags from the AwesomeWM doc

slots/client.lua

@@ -1,21 +0,0 @@
-local client_slots = {}
-
-function client_slots.append_mousebindings(params)
-    local amouse = require "awful.mouse"
-
-    for _, bindings in pairs(params.mousebindings) do
-        amouse.append_client_mousebindings(bindings)
-    end
-end
-
-function client_slots.append_keybindings(params)
-    local akeyboard = require "awful.keyboard"
-
-    for _, bindings in pairs(params.keybindings) do
-        akeyboard.append_client_keybindings(bindings)
-    end
-end
-
-return client_slots
-
--- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

slots/init.lua

@@ -1,10 +0,0 @@
-local aslot_slots = {}
-
-aslot_slots.client = require "awesome-slot.slots.client"
-aslot_slots.ruled = require "awesome-slot.slots.ruled"
-aslot_slots.screen = require "awesome-slot.slots.screen"
-aslot_slots.tag = require "awesome-slot.slots.tag"
-
-return aslot_slots
-
--- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

slots/ruled.lua

@@ -1,21 +0,0 @@
-local ruled_slots = {}
-
-function ruled_slots.append_client_rules(params)
-    local rclient = require "ruled.client"
-
-    for _, rule in pairs(params.rules) do
-        rclient.append_rule(rule)
-    end
-end
-
-function ruled_slots.append_notification_rules(params)
-    local rnotification = require "ruled.notification"
-
-    for _, rule in pairs(params.rules) do
-        rnotification.append_rule(rule)
-    end
-end
-
-return ruled_slots
-
--- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

slots/screen.lua

@@ -1,25 +0,0 @@
-local screen_slots = {}
-
-function screen_slots.wallpaper(screen, params)
-    local beautiful = require "beautiful"
-    local gwallpaper = require "gears.wallpaper"
-
-    params = params or {
-        wallpaper = beautiful.wallpaper,
-    }
-
-    local wallpaper = params.wallpaper
-
-    if wallpaper then
-        -- If wallpaper is a function, call it with the screen
-        if type(wallpaper) == "function" then
-            wallpaper = wallpaper(screen)
-        end
-
-        gwallpaper.maximized(wallpaper, screen, true)
-    end
-end
-
-return screen_slots
-
--- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

slots/tag.lua

@@ -1,11 +0,0 @@
-local tag_slots = {}
-
-function tag_slots.default_layouts(params)
-    local alayout = require "awful.layout"
-
-    alayout.append_default_layouts(params.layouts)
-end
-
-return tag_slots
-
--- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

src/awesome-slot/init.lua

@@ -46,43 +46,43 @@
 local gtable = require "gears.table"
 
 local capi = {
-    client = _G.client,
-    screen = _G.screen,
-    tag = _G.tag,
+   client = _G.client,
+   screen = _G.screen,
+   tag = _G.tag,
 }
 
 local awesome_slot = {
-    mt = {},
+   mt = {},
 
-    --- Slots defined by this module.
-    -- @table awesome_slot.slots
-    slots = require "awesome-slot.slots",
+   --- Slots defined by this module.
+   -- @table awesome_slot.slots
+   slots = require "awesome-slot.slots",
 
-    --- Special objects that require a static connection instead of object level connection.
-    -- @table awesome_slot.static_connect
-    static_connect = {
-        client = capi.client,
-        screen = capi.screen,
-        tag = capi.tag,
-        ruled_client = require "ruled.client",
-        ruled_notification = require "ruled.notification",
-    },
+   --- Special objects that require a static connection instead of object level connection.
+   -- @table awesome_slot.static_connect
+   static_connect = {
+      client = capi.client,
+      screen = capi.screen,
+      tag = capi.tag,
+      ruled_client = require "ruled.client",
+      ruled_notification = require "ruled.notification",
+   },
 
-    _private = {
-        registered_slots = {},
-    },
+   _private = {
+      registered_slots = {},
+   },
 }
 
 local function generate_id(base_id)
-    local id = base_id
-    local n = 0
+   local id = base_id
+   local n = 0
 
-    while awesome_slot.slots[id] ~= nil do
-        n = n + 1
-        id = base_id .. "_#" .. n
-    end
+   while awesome_slot.slots[id] ~= nil do
+      n = n + 1
+      id = base_id .. "_#" .. n
+   end
 
-    return id
+   return id
 end
 
 --- Find a previously registered slot.
@@ -93,11 +93,11 @@ end
 -- @treturn Slot The slot.
 -- @staticfct awesome_slot.get_slot
 function awesome_slot.get_slot(slot)
-    assert(slot)
-    local id = type(slot) == "string" and slot or slot.id
-    assert(id, "Slot not found!")
+   assert(slot)
+   local id = type(slot) == "string" and slot or slot.id
+   assert(id, "Slot not found!")
 
-    return awesome_slot._private.registered_slots[id]
+   return awesome_slot._private.registered_slots[id]
 end
 
 --- Create a new Slot instance.
@@ -108,36 +108,36 @@ end
 -- @tparam string params.signal The signal the slot connects to.
 -- @tparam function params.slot The callback function to connect to the signal.
 -- @tparam table params.slot_params The parameters to pass to the callback
---   function. (The signal will invok the callback function with this table as
+--   function. (The signal will invoke the callback function with this table as
 --   parameter)
 -- @tparam[opt=false] boolean params.connect Connect the slot now.
 -- @treturn Slot The created Slot instance.
 -- @constructorfct awesome_slot
 function awesome_slot.create(params)
-    local slot = {}
+   local slot = {}
 
-    slot.id = generate_id(params.id or "UNNAMED_SLOT")
-    slot.target = params.target
-    slot.signal = params.signal
-    slot.connected = false
+   slot.id = generate_id(params.id or "UNNAMED_SLOT")
+   slot.target = params.target
+   slot.signal = params.signal
+   slot.connected = false
 
-    if params.slot_params then
-        slot.params = params.slot_params
-        slot.callback = function()
-            params.slot(slot.params)
-        end
-    else
-        slot.callback = params.slot
-    end
+   if params.slot_params then
+      slot.params = params.slot_params
+      slot.callback = function()
+         params.slot(slot.params)
+      end
+   else
+      slot.callback = params.slot
+   end
 
-    -- Insert the new slot into the slots list
-    awesome_slot._private.registered_slots[slot.id] = slot
+   -- Insert the new slot into the slots list
+   awesome_slot._private.registered_slots[slot.id] = slot
 
-    if params.connect then
-        awesome_slot.connect(slot)
-    end
+   if params.connect then
+      awesome_slot.connect(slot)
+   end
 
-    return slot
+   return slot
 end
 
 --- Remove a registered slot and disconnect it.
@@ -145,13 +145,13 @@ end
 -- @tparam Slot slot The slot to remove.
 -- @staticfct awesome_slot.remove
 function awesome_slot.remove(slot)
-    local s = awesome_slot.get_slot(slot)
+   local s = awesome_slot.get_slot(slot)
 
-    if s.connected then
-        awesome_slot.disconnect_slot(s)
-    end
+   if s.connected then
+      awesome_slot.disconnect_slot(s)
+   end
 
-    awesome_slot._private.registered_slots[s.id] = nil
+   awesome_slot._private.registered_slots[s.id] = nil
 end
 
 --- Connect a slot to its signal.
@@ -160,20 +160,20 @@ end
 -- @treturn Slot The slot.
 -- @staticfct awesome_slot.connect
 function awesome_slot.connect(slot)
-    local s = awesome_slot.get_slot(slot)
+   local s = awesome_slot.get_slot(slot)
 
-    -- Some modules expose a static connect_signals function
-    -- at the module level, while other tables/objects inheriting from
-    -- gears.object implement the signal connection API at the instance level.
-    if gtable.hasitem(awesome_slot.static_connect, s.target) then
-        s.target.connect_signal(s.signal, s.callback)
-    else
-        s.target:connect_signal(s.signal, s.callback)
-    end
+   -- Some modules expose a static connect_signals function
+   -- at the module level, while other tables/objects inheriting from
+   -- gears.object implement the signal connection API at the instance level.
+   if gtable.hasitem(awesome_slot.static_connect, s.target) then
+      s.target.connect_signal(s.signal, s.callback)
+   else
+      s.target:connect_signal(s.signal, s.callback)
+   end
 
-    s.connected = true
+   s.connected = true
 
-    return s
+   return s
 end
 
 --- Disconnect a slot from its signal.
@@ -182,24 +182,22 @@ end
 -- @treturn Slot The slot.
 -- @staticfct awesome_slot.disconnect
 function awesome_slot.disconnect(slot)
-    local s = awesome_slot.get_slot(slot)
+   local s = awesome_slot.get_slot(slot)
 
-    -- Please check the `:connect_slot` method to understand why we do this.
-    if gtable.hasitem(awesome_slot.static_connect, s.target) then
-        s.target.disconnect_slot(s.signal, s.callback)
-    else
-        s.target:disconnect_slot(s.signal, s.callback)
-    end
+   -- Please check the `:connect_slot` method to understand why we do this.
+   if gtable.hasitem(awesome_slot.static_connect, s.target) then
+      s.target.disconnect_slot(s.signal, s.callback)
+   else
+      s.target:disconnect_slot(s.signal, s.callback)
+   end
 
-    s.connected = false
+   s.connected = false
 
-    return s
+   return s
 end
 
 function awesome_slot.mt:__call(...) -- luacheck: ignore unused argument self
-    return awesome_slot.create(...)
+   return awesome_slot.create(...)
 end
 
 return setmetatable(awesome_slot, awesome_slot.mt)
-
--- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

src/awesome-slot/slots/client.lua

@@ -0,0 +1,19 @@
+local client_slots = {}
+
+function client_slots.append_mousebindings(params)
+   local mouse = require "awful.mouse"
+
+   for _, bindings in pairs(params.mousebindings) do
+      mouse.append_client_mousebindings(bindings)
+   end
+end
+
+function client_slots.append_keybindings(params)
+   local keyboard = require "awful.keyboard"
+
+   for _, bindings in pairs(params.keybindings) do
+      keyboard.append_client_keybindings(bindings)
+   end
+end
+
+return client_slots

src/awesome-slot/slots/init.lua

@@ -0,0 +1,8 @@
+local slots = {}
+
+slots.client = require "awesome-slot.slots.client"
+slots.ruled = require "awesome-slot.slots.ruled"
+slots.screen = require "awesome-slot.slots.screen"
+slots.tag = require "awesome-slot.slots.tag"
+
+return slots

src/awesome-slot/slots/ruled.lua

@@ -0,0 +1,19 @@
+local ruled_slots = {}
+
+function ruled_slots.append_client_rules(params)
+   local client = require "ruled.client"
+
+   for _, rule in pairs(params.rules) do
+      client.append_rule(rule)
+   end
+end
+
+function ruled_slots.append_notification_rules(params)
+   local notification = require "ruled.notification"
+
+   for _, rule in pairs(params.rules) do
+      notification.append_rule(rule)
+   end
+end
+
+return ruled_slots

src/awesome-slot/slots/screen.lua

@@ -0,0 +1,23 @@
+local screen_slots = {}
+
+function screen_slots.wallpaper(screen, params)
+   local beautiful = require "beautiful"
+   local wallpaper = require "gears.wallpaper"
+
+   params = params or {
+      wallpaper = beautiful.wallpaper,
+   }
+
+   local w = params.wallpaper
+
+   if w then
+      -- If wallpaper is a function, call it with the screen
+      if type(w) == "function" then
+         w = w(screen)
+      end
+
+      wallpaper.maximized(w, screen, true)
+   end
+end
+
+return screen_slots

src/awesome-slot/slots/tag.lua

@@ -0,0 +1,9 @@
+local tag_slots = {}
+
+function tag_slots.default_layouts(params)
+   local layout = require "awful.layout"
+
+   layout.append_default_layouts(params.layouts)
+end
+
+return tag_slots

stylua.toml

@@ -1,6 +0,0 @@
-column_width = 80
-line_endings = "Unix"
-indent_type = "Spaces"
-indent_width = 4
-quote_style = "AutoPreferDouble"
-no_call_parentheses = true