Documentation updates

.github/workflows/ci.yml

@@ -14,4 +14,5 @@ jobs:
       with:
         extra_nix_config: "system-features = kvm nixos-test"
     - run: nix flake check -L --keep-going
-    - run: nix flake check -L --keep-going ./example
+    - run: nix flake check -L --keep-going ./examples/homeManagerFlake
+    - run: nix flake check -L --keep-going ./examples/systemFlake

README.md

@@ -3,94 +3,85 @@
 This project aims to provide [Home Manager][home-manager] modules which allow you
 to configure KDE Plasma using Nix.
 
-Configuration is broken down into three layers:
-
-  1. High-level interface like many Home Manager modules:
-
-     ```nix
-     {
-       programs.plasma = {
-         workspace = {
-           clickItemTo = "select";
-           tooltipDelay = 5;
-           theme = "breeze-dark";
-           colorScheme = "BreezeDark";
-           wallpaper = "${pkgs.libsForQt5.plasma-workspace-wallpapers}/share/wallpapers/Kay/contents/images/1080x1920.png";
-         };
-
-         kwin.titlebarButtons = {
-          left = [ "on-all-desktops" "keep-above-windows" ];
-          right = [ "help" "minimize" "maximize" "close" ]
-        };
-
-         spectacle.shortcuts = {
-           captureActiveWindow = "Meta+Print";
-           captureCurrentMonitor = "Print";
-           captureEntireDesktop = "Shift+Print";
-           captureRectangularRegion = "Meta+Shift+S";
-           captureWindowUnderCursor = "Meta+Ctrl+Print";
-           launch = "Meta+S";
-           launchWithoutCapturing = "Meta+Alt+S";
-         };
-       };
-     }
-     ```
-
-     This layer is doesn't currently have many options.  If using a
-     high-level interface like this sounds interesting to you please
-     consider contributing more options.
-
-  2. Mid-level interface:
-
-     ```nix
-     {
-       programs.plasma = {
-         shortcuts.kwin = {
-           "Switch Window Down" = "Meta+J";
-           "Switch Window Left" = "Meta+H";
-           "Switch Window Right" = "Meta+L";
-           "Switch Window Up" = "Meta+K";
-         };
-       };
-     }
-     ```
-
-     This layer is considered mid level because, while it generates a
-     great deal of configuration for you, you must still know the name
-     of the corresponding KDE setting to use it.  (See information
-     about the `rc2nix` tool below.)
-
-  3. A low-level interface:
-
-     ```nix
-     {
-       programs.plasma = {
-         configFile."baloofilerc"."Basic Settings"."Indexing-Enabled".value = false;
-       };
-     }
-     ```
-
-     The other two layers ultimately generate Nix configuration for
-     this low-level layer.  Configuration at this level is essentially
-     in the final state before being sent to our custom
-     configuration-writing script (which is very similar to
-     `kwriteconfig5`).
-
-For some examples see the [example](./example/) directory.
-
-## Capturing Your Current Configuration
-
-To make it easier to migrate to Plasma Manger, and to help maintain
-your Nix configuration, this project includes a tool called `rc2nix`.
-
-This tool will read KDE configuration files and translate them to
-Nix.  The translated configuration is written to standard output.
-This makes it easy to:
-
-  * Generate an initial Plasma Manager configuration file.
-
-  * See what settings are changed by a GUI tool by capturing a file
-    before and after using the tool and then using `diff`.
+## Table of contents
+- [What's supported](#whats-supported)
+- [What's not supported](#whats-not-well-supported-at-the-moment)
+- [Getting started](#getting-started)
+- [Enabling declarative configuration](#make-your-configuration-more-declarative-with-overrideconfig)
+- [Capturing existing configuration](#capturing-your-current-configuration-with-rc2nix)
+- [Contributions and maintenance](#contributions-and-maintenance)
+- [Special thanks](#special-thanks)
+
+## What's supported
+At the moment `plasma-manager` supports configuring the following:
+- KDE configuration files (via the `files` module)
+- Global themes, colorschemes, icons, cursortheme, wallpaper (via the `workspace` module)
+- Configuration of spectacle (via the `spectacle` module)
+- Shortcuts (via the `shortcuts` module)
+- Hotkeys (via the `hotkeys` module)
+- Panels (via the `panels` module)
+- KDE apps (via the `apps` module). In particular the following kde apps have
+  modules in `plasma-manager`:
+  - kate
+  - konsole
+
+Additionally there are more functionality than just listed above, and more
+functionality to come in the future!
+
+## What's not well supported (at the moment)
+There also are some things which at the moment isn't very well supported, in
+particular:
+- Real-time updates of configuration without having to log out and back in
+- Configuration of LibInput devices (see https://github.com/pjones/plasma-manager/issues/47)
+- Usage of high-level modules in the configuration generated by `rc2nix`
+
+There may also be more things we aren't aware of. If you find some other
+limitations don't hesitate to open an issue or submit a pr.
+
+## Getting started
+We provide some examples to help you get started. These are located in the
+[examples](./examples/) directory. Here you in particular can find:
+- [An example flake.nix for usage with home-manager only](./examples/homeManagerFlake//flake.nix)
+- [An example flake.nix for usage with the system configuration](./examples/systemFlake/flake.nix)
+- [An example home.nix showing some of the capabilities of plasma-manager](./examples/home.nix)
+
+With more to come! These should give you some idea how to get started with
+`plasma-manager`.
+
+## Make your configuration more declarative with overrideConfig
+By default `plasma-manager` will simply write the specified configurations to
+various config-files and leave all other options alone. This way settings not
+specified in `plasma-manager` will be left alone, meaning that configurations
+made outside `plasma-manager` will still be set. This can lead to different
+settings on different machines even with the same `plasma-manager`
+configuration. If you like a declarative approach better consider enabling
+`overrideConfig`. This makes it so all options not set by `plasma-manager` will
+be set to the default on login. In practice this then becomes a declarative
+setup, much like what you would expect from most `home-manager` options/modules.
+
+One thing to keep in mind is that enabling this option will delete all the KDE
+config-files on `home-manager` activation, and replace them with config-files
+generated by `plasma-manager`. Therefore make sure you backup your KDE
+config-files before enabling this option if you don't want to lose them.
+
+## Capturing Your Current Configuration with rc2nix
+
+To make it easier to migrate to `plasma-manager`, and to help maintain your Nix
+configuration when not using `overrideConfig`, this project includes a tool
+called `rc2nix`.
+
+This tool will read KDE configuration files and translate them to Nix.  The
+translated configuration is written to standard output.  This makes it easy to:
+
+- Generate an initial Plasma Manager configuration file.
+- See what settings are changed by a GUI tool by capturing a file
+  before and after using the tool and then using `diff`.
+
+Keep in mind that the `rc2nix` module isn't perfect and often will give somewhat
+suboptimal configurations (it will in some cases prefer using the `files` module
+when better configurations can be achieved using higher-level modules). However,
+it is still a useful tool to quickly get your configuration up and running or
+converting config-files generated by the gui settings app to nix expressions.
 
 To run the `rc2nix` tool without having to clone this repository run
 the following shell command:
@@ -101,18 +92,14 @@ nix run github:pjones/plasma-manager
 
 ## Contributions and Maintenance
 
-I consider this a community project and welcome all contributions.  If
-there's enough interest I would love to move this into
-[nix-community][] once it has matured.
-
-That said, this project works well enough for my needs.  I don't have
-enough free time to maintain this project on my own.  Therefore I
-won't be able to fix issues or implement new features without help.
+This is a community project and we welcome all contributions.  If there's enough
+interest we would love to move this into [nix-community] once it has matured.
 
 ## Special Thanks
 
-This work was inspired by the suggestions on [Home Manger Issue
-#607][hm607] by people such as [bew](https://github.com/bew) and [kurnevsky](https://github.com/kurnevsky).  Thank you.
+This work was inspired by the suggestions on [Home Manger Issue #607][hm607] by
+people such as [bew](https://github.com/bew) and
+[kurnevsky](https://github.com/kurnevsky).  Thank you.
 
 [home-manager]: https://github.com/nix-community/home-manager
 [hm607]: https://github.com/nix-community/home-manager/issues/607

example/home.nix → examples/home.nix

@@ -1,5 +1,7 @@
 { pkgs, ... }:
 {
+  home.stateVersion = "23.11";
+
   programs.plasma = {
     enable = true;
 
@@ -26,11 +28,23 @@
         location = "bottom";
         widgets = [
           "org.kde.plasma.kickoff"
-          "org.kde.plasma.icontasks"
+          # We can also configure the widgets. For example if you want to pin
+          # konsole and dolphin to the task-launcher the following widget will
+          # have that.
+          {
+            name = "org.kde.plasma.icontasks";
+            config = {
+              General.launchers = [
+                "applications:org.kde.dolphin.desktop"
+                "applications:org.kde.konsole.desktop"
+              ];
+            };
+          }
           "org.kde.plasma.marginsseperator"
           "org.kde.plasma.systemtray"
           "org.kde.plasma.digitalclock"
         ];
+        hiding = "autohide";
       }
       # Global menu at the top
       {

examples/homeManagerFlake/flake.nix

@@ -0,0 +1,45 @@
+{
+  description = "Plasma Manager Example with standalone home-manager flake";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-23.11";
+    home-manager = {
+      url = "github:nix-community/home-manager/release-23.11";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+    plasma-manager = {
+      url = "github:pjones/plasma-manager";
+      inputs.nixpkgs.follows = "nixpkgs";
+      inputs.home-manager.follows = "home-manager";
+    };
+  };
+
+  outputs = inputs@ { nixpkgs, home-manager, plasma-manager, ... }:
+    let
+      # Replace with your username
+      username = "jdoe";
+
+      # Replace with the fitting architecture
+      system = "x86_64-linux";
+    in
+    {
+      # Replace `standAloneConfig` with the name of your configuration (your `username` or `"username@hostname"`)
+      homeConfigurations.standAloneConfig = home-manager.lib.homeManagerConfiguration {
+        pkgs = import nixpkgs { inherit system; };
+
+        modules = [
+          inputs.plasma-manager.homeManagerModules.plasma-manager
+
+          # Specify the path to your home configuration here:
+          ../home.nix
+
+          {
+            home = {
+              inherit username;
+              homeDirectory = "/home/${username}";
+            };
+          }
+        ];
+      };
+    };
+}