Docs revamp (#1046)

- Separated out the YAML and C# docs - Filled out the YAML docs for existing functionality - Added inheritance for common YAML and C# docs - Filled out the layout engines YAML docs - Minor styling improvements
dalyIsaac · Oct 6, 2024 · 1d0264c · 1d0264c
1 parent 52e2748
commit 1d0264c
Show file tree

Hide file tree

Showing 80 changed files with 973 additions and 624 deletions.
diff --git a/.github/workflows/docs_commit.yml b/.github/workflows/docs_commit.yml
@@ -6,6 +6,7 @@ on:
       - .github/workflows/docs_commit.yml
       - docs/**
       - toc.yml
+      - src/**
 
 env:
   # We install the packages to the D:\ drive to avoid the slow IO on the C:\ drive.

diff --git a/docs/docs/customize/styling.md → docs/_common/core/styling.md b/docs/docs/customize/styling.md → docs/_common/core/styling.md
@@ -1,6 +1,4 @@
-# Styling
-
-Whim uses XAML resources to style the appearance of certain user interfaces such as the [Bar Plugin](../plugins/bar.md). By default, Whim loads its resources from [Defaults.xaml](https://github.com/dalyIsaac/Whim/blob/main/src/Whim/Resources/Defaults.xaml).
+Whim uses XAML resources to style the appearance of certain user interfaces such as the [Bar Plugin](../../configure/plugins/bar.md). By default, Whim loads its resources from [Defaults.xaml](https://github.com/dalyIsaac/Whim/blob/main/src/Whim/Resources/Defaults.xaml). <!-- markdownlint-disable-line MD041 -->
 
 ## Loading custom dictionaries
 

diff --git a/docs/docs/plugins/command-palette.md → docs/_common/plugins/command-palette.md b/docs/docs/plugins/command-palette.md → docs/_common/plugins/command-palette.md
@@ -1,41 +1,4 @@
-# Command Palette Plugin
-
-The <xref:Whim.CommandPalette.CommandPalettePlugin> provides a fuzzy command palette, loaded with all the <xref:Whim.ICommand>s registered with the <xref:Whim.ICommandManager>.
-
-The command palette uses a port of Visual Studio Code's fuzzy search algorithm.
-
-![Command palette demo](../../images/command-palette-demo.gif)
-
-## Configuration
-
-The <xref:Whim.CommandPalette.CommandPaletteConfig> can be used to configure the command palette. The <xref:Whim.CommandPalette.CommandPaletteConfig.ActivationConfig> can be used to configure the default commands and matcher to use.
-
-Custom instances of the command palette can be activated by calling <xref:Whim.CommandPalette.CommandPalettePlugin.Activate(Whim.CommandPalette.BaseVariantConfig)>.
-
-## Example Config
-
-```csharp
-#r "WHIM_PATH\whim.dll"
-#r "WHIM_PATH\plugins\Whim.CommandPalette\Whim.CommandPalette.dll"
-
-using Whim;
-using Whim.CommandPalette;
-
-void DoConfig(IContext context)
-{
-  // ...
-
-  CommandPaletteConfig commandPaletteConfig = new(context);
-  CommandPalettePlugin commandPalettePlugin = new(context, commandPaletteConfig);
-  context.PluginManager.AddPlugin(commandPalettePlugin);
-
-  // ...
-}
-
-return DoConfig;
-```
-
-## Commands
+## Commands <!-- markdownlint-disable-line MD041 -->
 
 | Identifier                                                | Title                              | Keybind                                          |
 | --------------------------------------------------------- | ---------------------------------- | ------------------------------------------------ |

diff --git a/docs/_common/plugins/focus-indicator.md b/docs/_common/plugins/focus-indicator.md
@@ -0,0 +1,8 @@
+## Commands <!-- markdownlint-disable-line MD041 -->
+
+| Identifier                            | Title                                         | Keybind            |
+| ------------------------------------- | --------------------------------------------- | ------------------ |
+| `whim.focus_indicator.show`           | Show focus indicator                          | No default keybind |
+| `whim.focus_indicator.toggle`         | Toggle focus indicator                        | No default keybind |
+| `whim.focus_indicator.toggle_fade`    | Toggle whether the focus indicator fades      | No default keybind |
+| `whim.focus_indicator.toggle_enabled` | Toggle whether the focus indicator is enabled | No default keybind |
diff --git a/docs/_common/plugins/gaps.md b/docs/_common/plugins/gaps.md
@@ -0,0 +1,8 @@
+## Commands <!-- markdownlint-disable-line MD041 -->
+
+| Identifier                 | Title              | Keybind                                                            |
+| -------------------------- | ------------------ | ------------------------------------------------------------------ |
+| `whim.gaps.outer.increase` | Increase outer gap | <kbd>Win</kbd> + <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>L</kbd> |
+| `whim.gaps.outer.decrease` | Decrease outer gap | <kbd>Win</kbd> + <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>H</kbd> |
+| `whim.gaps.inner.increase` | Increase inner gap | <kbd>Win</kbd> + <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd> |
+| `whim.gaps.inner.decrease` | Decrease inner gap | <kbd>Win</kbd> + <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>J</kbd> |
diff --git a/docs/_common/plugins/layout-preview.md b/docs/_common/plugins/layout-preview.md
@@ -0,0 +1,3 @@
+## Commands <!-- markdownlint-disable-line MD041 -->
+
+The `LayoutPreviewPlugin` has no commands.
diff --git a/docs/docs/plugins/slice-layout.md → docs/_common/plugins/slice-layout.md b/docs/docs/plugins/slice-layout.md → docs/_common/plugins/slice-layout.md
@@ -1,34 +1,4 @@
-# Slice Layout Plugin
-
-<xref:Whim.SliceLayout.SliceLayoutPlugin> provides commands and functionality for the <xref:Whim.SliceLayout.SliceLayoutEngine>.
-
-<xref:Whim.SliceLayout.SliceLayoutPlugin> does not load the <xref:Whim.SliceLayout.SliceLayoutEngine> - that is done when creating a workspace via the <xref:Whim.AddWorkspaceTransform>.
-
-For more about the `SliceLayoutEngine`, see the [Layout Engines](../customize//layout-engines.md#slicelayoutengine) page.
-
-## Example Config
-
-```csharp
-#r "WHIM_PATH\whim.dll"
-#r "WHIM_PATH\plugins\Whim.SliceLayout\Whim.SliceLayout.dll"
-
-using Whim;
-using Whim.SliceLayout;
-
-void DoConfig(IContext context)
-{
-  // ...
-
-  SliceLayoutPlugin sliceLayoutPlugin = new(context);
-  context.PluginManager.AddPlugin(sliceLayoutPlugin);
-
-  // ...
-}
-
-return DoConfig;
-```
-
-## Commands
+<!-- markdownlint-disable MD041 -->
 
 | Identifier                                    | Title                              | Keybind            |
 | --------------------------------------------- | ---------------------------------- | ------------------ |

diff --git a/docs/docs/plugins/tree-layout.md → docs/_common/plugins/tree-layout.md b/docs/docs/plugins/tree-layout.md → docs/_common/plugins/tree-layout.md
@@ -1,36 +1,4 @@
-# Tree Layout Plugin
-
-<xref:Whim.TreeLayout.TreeLayoutPlugin> provides commands and functionality for the <xref:Whim.TreeLayout.TreeLayoutEngine>.
-
-<xref:Whim.TreeLayout.TreeLayoutPlugin> does not load the <xref:Whim.TreeLayout.TreeLayoutEngine> - that is done when creating a workspace via the <xref:Whim.AddWorkspaceTransform>.
-
-For more about the `TreeLayoutEngine`, see the [Layout Engines](../customize/layout-engines.md#treelayoutengine) page.
-
-The [Tree Layout Bar plugin](./tree-layout-bar.md) provides a widget for the bar to set the direction to add the next window.
-
-## Example Config
-
-```csharp
-#r "WHIM_PATH\whim.dll"
-#r "WHIM_PATH\plugins\Whim.TreeLayout\Whim.TreeLayout.dll"
-
-using Whim;
-using Whim.TreeLayout;
-
-void DoConfig(IContext context)
-{
-  // ...
-
-  TreeLayoutPlugin treeLayoutPlugin = new(context);
-  context.PluginManager.AddPlugin(treeLayoutPlugin);
-
-  // ...
-}
-
-return DoConfig;
-```
-
-## Commands
+<!-- markdownlint-disable MD041 -->
 
 | Identifier                                  | Title                                          | Keybind                                                                |
 | ------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------- |

diff --git a/docs/_common/plugins/updater.md b/docs/_common/plugins/updater.md
@@ -0,0 +1,5 @@
+## Commands <!-- markdownlint-disable-line MD041 -->
+
+| Identifier           | Title             | Keybind            |
+| -------------------- | ----------------- | ------------------ |
+| `whim.updater.check` | Check for updates | No default keybind |
diff --git a/docs/docs/customize/commands.md → docs/configure/core/commands.md b/docs/docs/customize/commands.md → docs/configure/core/commands.md
@@ -6,7 +6,7 @@ Whim differentiates three types of commands.
 
 1. [Core commands](#core-commands) expose common functions as ready-to-use commands, many of which come with a default keybinding.
 2. [Plugin commands](#plugin-commands) are ready-to-use commands exposed by plugins.
-3. [Custom commands](#custom-commands) are user-defined commands, which can compose arbitrary functions.
+3. [Custom commands](../../script/core/commands.md) are user-defined commands, which can compose arbitrary functions.
 
 ## Core commands
 
@@ -48,27 +48,4 @@ Core commands have identifiers under the `whim.core` namespace.
 
 ## Plugin commands
 
-Plugin commands are namespaced by the string defined in the <xref:Whim.IPlugin.Name> property for plugins - for example, `whim.gaps` for [`GapsPlugin`](../plugins/gaps.md). For a list of available plugin commands, see the "Plugins" section.
-
-## Custom commands
-
-Custom commands can be created using the <xref:Whim.ICommandManager>. They are automatically added to the `whim.custom` namespace. For example, the following command closes the current tracked window:
-
-```csharp
-// Create the command.
-context.CommandManager.Add(
-    // Automatically namespaced to `whim.custom`.
-    identifier: "close_window",
-    title: "Close focused window",
-    callback: () =>
-    {
-        if (context.Store.Pick(Pickers.PickLastFocusedWindow).TryGet(out IWindow window))
-        {
-            window.Close();
-        }
-    }
-);
-
-// Create an associated keybind.
-context.KeybindManager.SetKeybind("whim.custom.close_window", new Keybind(IKeybind.WinAlt, VIRTUAL_KEY.VK_D));
-```
+Plugin commands are namespaced by the string defined in the <xref:Whim.IPlugin.Name> property for plugins - for example, `whim.gaps` for [`GapsPlugin`](../plugins/gaps.md). Commands are listed on the respective plugin documentation pages.
diff --git a/docs/configure/core/filtering.md b/docs/configure/core/filtering.md
@@ -0,0 +1,58 @@
+# Filters
+
+By default, Whim ignores a built-in list of windows that are known to cause problems with dynamic tiling window manager. Behind the scenes, Whim automatically updates the built-in list of ignored windows based on a subset of the rules from the community-driven [collection of application rules](https://github.com/LGUG2Z/komorebi-application-specific-configuration) managed by komorebi.
+
+## Custom Filtering Behavior
+
+The filters configuration tells Whim to ignore windows that match the specified criteria.
+
+You can filter windows by:
+
+- `window_class`
+- `process_file_name`
+- `title`
+- `title_regex`
+
+## Window Class Filter
+
+For example, to filter out Chromium windows with the class `Chrome_WidgetWin_1`, add the following to your configuration:
+
+```yaml
+filters:
+  entries:
+    - type: window_class
+      value: Chrome_WidgetWin_1
+```
+
+## Process File Name Filter
+
+For example, to filter out windows with the process file name `explorer.exe`, add the following to your configuration:
+
+```yaml
+filters:
+  entries:
+    - type: process_file_name
+      value: explorer.exe
+```
+
+## Title Filter
+
+For example, to filter out windows with the title `Untitled - Notepad`, add the following to your configuration:
+
+```yaml
+filters:
+  entries:
+    - type: title
+      value: Untitled - Notepad
+```
+
+## Title Match Filter
+
+For example, to filter out windows with the title that matches the regex `^Untitled - Notepad$`, add the following to your configuration:
+
+```yaml
+filters:
+  entries:
+    - type: title_regex
+      value: ^Untitled - Notepad$
+```
diff --git a/docs/configure/core/keybinds.md b/docs/configure/core/keybinds.md
@@ -0,0 +1,64 @@
+# Keybinds
+
+The keybinds configuration has a list of bindings that you can use to bind commands to key combinations.
+
+## Bindings
+
+A key modifier is a key that is pressed in combination with another key to perform a specific action. The `bindings` property is a list of keybinds that map a command to a key combination.
+
+Key modifiers can be any of the following:
+
+- `Ctrl`
+- `Control`
+- `LCtrl`
+- `LControl`
+- `RCtrl`
+- `RControl`
+- `Shift`
+- `LShift`
+- `RShift`
+- `Alt`
+- `LAlt`
+- `RAlt`
+- `Win`
+- `LWin`
+- `RWin`
+
+The associated key for each modifier can be any of the <xref:Windows.Win32.UI.Input.KeyboardAndMouse.VIRTUAL_KEY>s.
+
+## Commands
+
+A command is a string that represents a command that can be executed by Whim. The command can be a built-in command, a plugin command, or a custom command. For more, see the [Commands](commands.md) page.
+
+## Unify Key Modifiers
+
+To treat key modifiers like `LWin` and `RWin` the same, set `unify_key_modifiers` to `true`.
+
+## Keybinds Example
+
+```yaml
+keybinds:
+  entries:
+    - command: whim.core.focus_next_monitor
+      keybind: LCtrl+LShift+LAlt+K
+
+    - command: whim.core.focus_previous_monitor
+      keybind: LCtrl+LShift+LAlt+J
+
+    - command: whim.custom.next_layout_engine
+      keybind: LCtrl+LShift+LAlt+L
+
+    - command: whim.core.cycle_layout_engine.next
+      keybind: LCtrl+LShift+LAlt+L
+
+    - command: whim.core.cycle_layout_engine.previous
+      keybind: LCtrl+LShift+LAlt+Win+L
+
+    - command: whim.command_palette.find_focus_window
+      keybind: Win+LCtrl+F
+
+    - command: whim.core.exit_whim
+      keybind: Win+LCtrl+Q
+
+  unify_key_modifiers: true
+```
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,6 +6,7 @@ on: @@
           - .github/workflows/docs_commit.yml
           - docs/**
           - toc.yml
+          - src/**
     env:
       # We install the packages to the D:\ drive to avoid the slow IO on the C:\ drive.
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		## Commands <!-- markdownlint-disable-line MD041 -->

		The `LayoutPreviewPlugin` has no commands.