docs: improve examples, remove docs superseded by typespec docstrings (#279)

* chore(bling): uncomment example options

* refactor(brew): remove duplicate "configuration options" setting in README, improve TSP docs

* fix(chezmoi): make example an example and not a doc of the configuration options

* chore(rpm-ostree): remove fake example

examples should be runnable

* fix(rpm-ostree): add replacing packages to typespec schema

* fix(rpm-ostree): actually install the packages the repos are added for

* feat(rpm-ostree): showcase installing from URL and using optfix in example

* fix(rpm-ostree): add optfix to typespec

* fix(systemd): real-world example instead of configuration docs duplicate

modules/brew/README.md

@@ -51,8 +51,6 @@ The brew module installs [Homebrew / Linuxbrew](https://brew.sh/) on your system
 - `brew-update` runs at the specified time to update Brew to the latest version
 - `brew-upgrade` runs at the specified time to upgrade Brew packages
 
-## Configuration Options
-
 ### Update
 
 The Brew update operation updates the Brew binary to latest version.

modules/brew/brew.tsp

@@ -8,27 +8,35 @@ model BrewModule {
     */
     type: "brew";
 
-    /** Whether to auto-update the Brew binary. */
+    /** Whether to auto-update the Brew binary using a systemd service. */
     "auto-update"?: boolean = true;
 
-    /** Interval between Brew updates. */
+    /** Defines how often the Brew update service should run. The string is passed directly to `OnUnitInactiveSec` in systemd timer. (Syntax: ['1d', '6h', '10m']). */
     "update-interval"?: string = "6h";
 
-    /** Time delay after boot before first Brew update .*/
+    /** Time delay after system boot before the first Brew update runs. The string is passed directly to `OnBootSec` in systemd timer. (Syntax: ['1d', '6h', '10m']). */
     "update-wait-after-boot"?: string = "10min";
 
-    /** Wthether to auto-upgrade Brew packages. */
+    /** Whether to auto-upgrade all installed Brew packages using a systemd service. */
     "auto-upgrade"?: boolean = true;
 
-    /** Interval between Brew package upgrades. */
+    /** Defines how often the Brew upgrade service should run. The string is passed directly to `OnUnitInactiveSec` in systemd timer. (Syntax: ['1d', '6h', '10m']). */
     "upgrade-interval"?: string = "8h";
 
-    /** Time delay after boot before first Brew package upgrade. */
+    /** Time delay after system boot before the first Brew package upgrade runs. The string is passed directly to `OnBootSec` in systemd timer. (Syntax: ['1d', '6h', '10m']). */
     "upgrade-wait-after-boot"?: string = "30min";
 
-    /** Whether to apply nofile limits (limits for number of open files) for Brew installations. */
+    /** Whether to increase nofile limits (limits for number of open files) for Brew installations.
+     * When set to true, it increases the nofile limits to prevent certain "I/O heavy" Brew packages from failing due to "too many open files" error.
+     * However, it's important to note that increasing nofile limits can have potential security implications for malicious applications which would try to abuse storage I/O.
+     * Defaults to false for security purposes.
+     * 
+     * https://serverfault.com/questions/577437/what-is-the-impact-of-increasing-nofile-limits-in-etc-security-limits-conf
+     */
     "nofile-limits"?: boolean = false;
 
-    /** Whether to enable Brew analytics. */
+    /** Whether to enable Brew analytics. 
+     * The Homebrew project uses analytics to anonymously collect the information about Brew usage & your system in order to improve the experience of Brew users.  
+     */
     "brew-analytics"?: boolean = true;
 }

modules/brew/module.yml

@@ -4,19 +4,5 @@ readme: https://raw.githubusercontent.com/blue-build/modules/main/modules/brew/R
 typespec: https://raw.githubusercontent.com/blue-build/modules/main/modules/brew/brew.tsp
 example: |
   type: brew
-  # Auto-update Brew binary
-  auto-update: true # Optional - Default: true - Expects type: boolean
-  # Interval between Brew updates
-  update-interval: '6h' # Optional - Default: '6h' - Expects type: string
-  # Time delay after boot before first Brew update
-  update-wait-after-boot: '10min' # Optional - Default: '10min' - Expects type: string 
-  # Auto-upgrade Brew packages
-  auto-upgrade: true # Optional - Default: true - Expects type: boolean    
-  # Interval between Brew package upgrades
-  upgrade-interval: '8h' # Optional - Default: '8h' - Expects type: string
-  # Time delay after boot before first Brew upgrade
-  upgrade-wait-after-boot: '30min' # Optional - Default: '30min' - Expects type: string
-  # Apply nofile limits for Brew installations
-  nofile-limits: false # Optional - Default: false - Expects type: boolean
-  # Control Brew analytics
-  brew-analytics: true # Optional - Default: true - Expects type: boolean
+  nofile-limits: true # increase nofile limits
+  brew-analytics: false # disable telemetry