From 15571194489514f02423c272f65211d08808bdad Mon Sep 17 00:00:00 2001 From: vikingowl Date: Tue, 30 Dec 2025 08:49:30 +0100 Subject: [PATCH] docs: comprehensive documentation update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md: - Fix bundle package names (add meta- prefix) - Add Firefox support to bookmarks plugin description - Add system paths table (plugins, runtimes, example config) - Add Quick Start section for copying example config - Expand config example with providers section docs/PLUGINS.md: - Add Firefox support to bookmarks - Fix bundle package names - Remove outdated [plugins.weather] and [plugins.pomodoro] config examples docs/PLUGIN_DEVELOPMENT.md: - Fix Rust edition from 2024 to 2021 - Add position and priority fields to ProviderInfo - Add ProviderPosition enum documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 46 +++++++++++++++++++++++++------------- docs/PLUGINS.md | 30 ++++++++----------------- docs/PLUGIN_DEVELOPMENT.md | 13 +++++++++-- 3 files changed, 51 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 91e4b3f..1dc1904 100644 --- a/README.md +++ b/README.md @@ -32,10 +32,10 @@ yay -S owlry yay -S owlry-plugin-calculator owlry-plugin-weather # Or install bundles: -yay -S owlry-essentials # calculator, system, ssh, scripts, bookmarks -yay -S owlry-widgets # weather, media, pomodoro -yay -S owlry-tools # clipboard, emoji, websearch, filesearch, systemd -yay -S owlry-full # everything +yay -S owlry-meta-essentials # calculator, system, ssh, scripts, bookmarks +yay -S owlry-meta-widgets # weather, media, pomodoro +yay -S owlry-meta-tools # clipboard, emoji, websearch, filesearch, systemd +yay -S owlry-meta-full # everything # For custom Lua/Rune plugins yay -S owlry-lua # Lua 5.4 runtime @@ -53,7 +53,7 @@ yay -S owlry-rune # Rune runtime | `owlry-plugin-clipboard` | History via cliphist | | `owlry-plugin-emoji` | 400+ searchable emoji | | `owlry-plugin-scripts` | User scripts | -| `owlry-plugin-bookmarks` | Chrome, Brave, Edge bookmarks | +| `owlry-plugin-bookmarks` | Firefox, Chrome, Brave, Edge bookmarks | | `owlry-plugin-websearch` | Web search (`? query`) | | `owlry-plugin-filesearch` | File search (`/ filename`) | | `owlry-plugin-systemd` | User services with actions | @@ -158,6 +158,21 @@ Owlry follows the [XDG Base Directory Specification](https://specifications.free | `~/.local/share/owlry/scripts/` | User scripts | | `~/.local/share/owlry/frecency.json` | Usage history | +System locations: +| Path | Purpose | +|------|---------| +| `/usr/lib/owlry/plugins/*.so` | Installed native plugins | +| `/usr/lib/owlry/runtimes/*.so` | Lua/Rune script runtimes | +| `/usr/share/doc/owlry/config.example.toml` | Example configuration | + +### Quick Start + +```bash +# Copy example config +mkdir -p ~/.config/owlry +cp /usr/share/doc/owlry/config.example.toml ~/.config/owlry/config.toml +``` + ### Example Configuration ```toml @@ -169,8 +184,8 @@ tabs = ["app", "cmd", "uuctl"] # launch_wrapper = "uwsm app --" # Auto-detected [appearance] -width = 700 -height = 500 +width = 850 +height = 650 font_size = 14 border_radius = 12 # theme = "owl" # Or: catppuccin-mocha, nord, dracula, etc. @@ -178,17 +193,18 @@ border_radius = 12 [plugins] disabled = [] # Plugin IDs to disable, e.g., ["emoji", "pomodoro"] -# Per-plugin configuration (new in 0.4.0) -[plugins.weather] -provider = "wttr.in" # or: openweathermap, open-meteo -location = "Berlin" # city name or "lat,lon" -# api_key = "..." # Required for OpenWeatherMap +[providers] +applications = true # .desktop files +commands = true # PATH executables +frecency = true # Boost frequently used items +frecency_weight = 0.3 # 0.0-1.0 -[plugins.pomodoro] -work_mins = 25 # Work session duration -break_mins = 5 # Break duration +# Web search engine: google, duckduckgo, bing, startpage, brave, ecosia +search_engine = "duckduckgo" ``` +See `/usr/share/doc/owlry/config.example.toml` for all options with documentation. + ## Plugin System Owlry uses a modular plugin architecture. Plugins are loaded from: diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md index 3fdc42f..40626c6 100644 --- a/docs/PLUGINS.md +++ b/docs/PLUGINS.md @@ -143,9 +143,10 @@ chmod +x ~/.local/share/owlry/scripts/backup.sh **Prefix:** `:bm` **Package:** `owlry-plugin-bookmarks` -Browser bookmarks from Chromium-based browsers. +Browser bookmarks from Firefox and Chromium-based browsers. **Supported browsers:** +- Firefox (reads places.sqlite) - Google Chrome - Brave - Microsoft Edge @@ -236,13 +237,7 @@ Current weather displayed at the top of results. - OpenWeatherMap (requires API key) - Open-Meteo (no API key required) -**Configuration:** -```toml -[plugins.weather] -provider = "wttr.in" # or: openweathermap, open-meteo -location = "London" # city name or "lat,lon" (empty for auto-detect) -# api_key = "..." # Required for OpenWeatherMap -``` +**Note:** Weather configuration is currently embedded in the plugin. Future versions will support runtime configuration. **Features:** - Temperature, condition, humidity, wind speed @@ -274,13 +269,6 @@ MPRIS media player controls. Pomodoro timer with work/break cycles. -**Configuration:** -```toml -[plugins.pomodoro] -work_mins = 25 # Work session duration (default: 25) -break_mins = 5 # Break duration (default: 5) -``` - **Features:** - Configurable work session duration - Configurable break duration @@ -301,17 +289,17 @@ For convenience, plugins are available in bundle meta-packages: | Bundle | Plugins | |--------|---------| -| `owlry-essentials` | calculator, system, ssh, scripts, bookmarks | -| `owlry-widgets` | weather, media, pomodoro | -| `owlry-tools` | clipboard, emoji, websearch, filesearch, systemd | -| `owlry-full` | All of the above | +| `owlry-meta-essentials` | calculator, system, ssh, scripts, bookmarks | +| `owlry-meta-widgets` | weather, media, pomodoro | +| `owlry-meta-tools` | clipboard, emoji, websearch, filesearch, systemd | +| `owlry-meta-full` | All of the above | ```bash # Install everything -yay -S owlry-full +yay -S owlry-meta-full # Or pick a bundle -yay -S owlry-essentials owlry-widgets +yay -S owlry-meta-essentials owlry-meta-widgets ``` --- diff --git a/docs/PLUGIN_DEVELOPMENT.md b/docs/PLUGIN_DEVELOPMENT.md index 210377b..604a827 100644 --- a/docs/PLUGIN_DEVELOPMENT.md +++ b/docs/PLUGIN_DEVELOPMENT.md @@ -23,7 +23,7 @@ Edit `Cargo.toml`: [package] name = "owlry-plugin-myplugin" version = "0.1.0" -edition = "2024" +edition = "2021" [lib] crate-type = ["cdylib"] @@ -38,7 +38,7 @@ Edit `src/lib.rs`: use abi_stable::std_types::{ROption, RStr, RString, RVec}; use owlry_plugin_api::{ owlry_plugin, PluginInfo, PluginItem, ProviderHandle, ProviderInfo, - ProviderKind, API_VERSION, + ProviderKind, ProviderPosition, API_VERSION, }; extern "C" fn plugin_info() -> PluginInfo { @@ -59,6 +59,8 @@ extern "C" fn plugin_providers() -> RVec { icon: RString::from("application-x-executable"), provider_type: ProviderKind::Static, type_id: RString::from("myplugin"), + position: ProviderPosition::Normal, + priority: 0, // Use frecency-based ordering }].into() } @@ -198,12 +200,19 @@ pub struct ProviderInfo { pub icon: RString, // Default icon name pub provider_type: ProviderKind, // Static or Dynamic pub type_id: RString, // Short ID for badges + pub position: ProviderPosition, // Normal or Widget + pub priority: i32, // Result ordering (higher = first) } pub enum ProviderKind { Static, // Items loaded at startup via refresh() Dynamic, // Items computed per-query via query() } + +pub enum ProviderPosition { + Normal, // Standard results (sorted by score/frecency) + Widget, // Displayed at top when query is empty +} ``` ### PluginItem