Merge pull request #584 from JakeStanger/docs/conf-schema

JSON Schema

.github/workflows/deploy.yml

@@ -6,20 +6,13 @@ on:
       - v[0-9]+.[0-9]+.[0-9]+
 
 jobs:
-  deploy:
+  release:
+    name: 'Create Release'
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v3
 
-      - uses: actions-rs/toolchain@v1
-        with:
-          toolchain: stable
-          override: true
-
-      - name: Install build deps
-        run: ./.github/scripts/ubuntu_setup.sh
-
       - name: Update CHANGELOG
         id: changelog
         uses: Requarks/changelog-action@v1
@@ -41,9 +34,54 @@ jobs:
         uses: stefanzweifel/git-auto-commit-action@v4
         with:
           branch: master
-          commit_message: 'docs: update CHANGELOG.md for ${{ github.ref_name }} [skip ci]'
+          commit_message: 'chore: update CHANGELOG.md for ${{ github.ref_name }} [skip ci]'
           file_pattern: CHANGELOG.md
 
-      - uses: katyo/publish-crates@v1
+
+  publish-crate:
+    name: 'Publish Crate'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+
+      - name: Install build deps
+        run: ./.github/scripts/ubuntu_setup.sh
+
+      - name: Publish crate
+        uses: katyo/publish-crates@v1
         with:
           registry-token: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+
+  publish-schema:
+    name: 'Publish Schema'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: Swatinem/rust-cache@v2
+        name: Cache dependencies
+
+      - name: Install build deps
+        run: ./.github/scripts/ubuntu_setup.sh
+
+      - name: Build schema
+        run: cargo build --features schema -- --print-schema > target/schema-${{ github.ref_name }}.json
+
+      - name: Copy file via SSH
+        uses: appleboy/[email protected]
+        with:
+          host: ${{ secrets.SSH_HOST }}
+          port: ${{ secrets.SSH_PORT }}
+          username: ${{ secrets.SSH_USERNAME }}
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          source: "target/schema-${{ github.ref_name }}.json"
+          target: /storage/Public/github/ironbar
+          strip_components: 1

.github/workflows/schema.yml

@@ -0,0 +1,41 @@
+name: Publish Schema
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ "master" ]
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: '-Dwarnings'
+
+jobs:
+  publish-schema:
+    name: 'Publish Schema'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: Swatinem/rust-cache@v2
+        name: Cache dependencies
+
+      - name: Install build deps
+        run: ./.github/scripts/ubuntu_setup.sh
+
+      - name: Build
+        run: cargo build --features schema
+
+      - name: Print schema
+        run: cargo run --features schema -- --print-schema > target/schema.json
+
+      - name: Copy file via SSH
+        uses: appleboy/[email protected]
+        with:
+          host: ${{ secrets.SSH_HOST }}
+          port: ${{ secrets.SSH_PORT }}
+          username: ${{ secrets.SSH_USERNAME }}
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          source: "target/schema.json"
+          target: /storage/Public/github/ironbar
+          strip_components: 1

Cargo.toml

@@ -76,6 +76,8 @@ workspaces = ["futures-lite"]
 "workspaces+sway" = ["workspaces", "swayipc-async"]
 "workspaces+hyprland" = ["workspaces", "hyprland"]
 
+schema = ["dep:schemars"]
+
 [dependencies]
 # core
 gtk = "0.18.1"
@@ -157,3 +159,6 @@ regex = { version = "1.10.4", default-features = false, features = [
   "std",
 ], optional = true } # music, sys_info
 zbus = { version = "3.15.2", default-features = false, features = ["tokio"], optional = true } # notifications, upower
+
+# schema
+schemars = { version = "0.8.19", optional = true }

docs/Compiling.md

@@ -101,6 +101,9 @@ cargo build --release --no-default-features \
 | workspaces+all      | Enables the `workspaces` module with support for all compositors.                 |
 | workspaces+sway     | Enables the `workspaces` module with support for Sway.                            |
 | workspaces+hyprland | Enables the `workspaces` module with support for Hyprland.                        |
+| **Other**           |                                                                                   |
+| schema              | Enables JSON schema support and the CLI `--print-schema` flag.                    |
+
 
 ## Speeding up compiling
 

docs/Configuration guide.md

@@ -20,11 +20,18 @@ Ironbar supports a range of configuration formats, so you can pick your favourit
 - `config.json`
 - `config.toml`
 - `config.yaml`
-- `config.corn` (Experimental, includes variable support for re-using blocks.
+- `config.corn` (Includes variable support for re-using blocks.
   See [here](https://github.com/jakestanger/corn) for info)
 
 You can also override the default config path using the `IRONBAR_CONFIG` environment variable.
 
+A hosted schema is available for the latest Git version ~~and each versioned release~~.
+JSON and YAML both support schema checking by adding the `$schema` key 
+to the top level of your config.
+
+- master: `https://f.jstanger.dev/github/ironbar/schema.json`
+- ~~release: `https://f.jstanger.dev/github/ironbar/schema-v0.16.0.json`~~ *(Not released yet)*
+
 ## 2. Pick your use-case
 
 Ironbar gives you a few ways to configure the bar to suit your needs.

examples/config.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://f.jstanger.dev/github/ironbar/schema.json",
   "anchor_to_edges": true,
   "position": "bottom",
   "icon_theme": "Paper",

examples/config.yaml

@@ -1,3 +1,4 @@
+$schema: https://f.jstanger.dev/github/ironbar/schema.json
 anchor_to_edges: true
 position: bottom
 icon_theme: Paper

src/cli.rs

@@ -9,6 +9,12 @@ pub struct Args {
     #[command(subcommand)]
     pub command: Option<Command>,
 
+    /// Prints the config JSON schema to `stdout`
+    /// and exits.
+    #[cfg(feature = "schema")]
+    #[arg(long("print-schema"))]
+    pub print_schema: bool,
+
     /// `bar_id` argument passed by `swaybar_command`.
     /// Not used.
     #[arg(short('b'), hide(true))]

src/config/common.rs

@@ -16,6 +16,7 @@ use tracing::trace;
 /// see [here](script).
 /// For information on styling, please see the [styling guide](styling-guide).
 #[derive(Debug, Default, Deserialize, Clone)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 pub struct CommonConfig {
     /// Sets the unique widget name,
     /// allowing you to target it in CSS using `#name`.
@@ -160,6 +161,7 @@ pub struct CommonConfig {
 
 #[derive(Debug, Deserialize, Clone)]
 #[serde(rename_all = "snake_case")]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 pub enum TransitionType {
     None,
     Crossfade,
@@ -169,6 +171,7 @@ pub enum TransitionType {
 
 #[derive(Debug, Default, Deserialize, Clone, Copy)]
 #[serde(rename_all = "snake_case")]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 pub enum ModuleOrientation {
     #[default]
     #[serde(alias = "h")]

src/config/mod.rs

@@ -36,11 +36,15 @@ use color_eyre::Result;
 use serde::Deserialize;
 use std::collections::HashMap;
 
+#[cfg(feature = "schema")]
+use schemars::JsonSchema;
+
 pub use self::common::{CommonConfig, ModuleOrientation, TransitionType};
 pub use self::truncate::TruncateMode;
 
 #[derive(Debug, Deserialize, Clone)]
 #[serde(tag = "type", rename_all = "snake_case")]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
 pub enum ModuleConfig {
     #[cfg(feature = "cairo")]
     Cairo(Box<CairoModule>),
@@ -117,13 +121,15 @@ impl ModuleConfig {
 }
 
 #[derive(Debug, Clone)]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
 pub enum MonitorConfig {
     Single(BarConfig),
     Multiple(Vec<BarConfig>),
 }
 
 #[derive(Debug, Deserialize, Copy, Clone, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
 pub enum BarPosition {
     Top,
     Bottom,
@@ -138,6 +144,7 @@ impl Default for BarPosition {
 }
 
 #[derive(Debug, Default, Deserialize, Copy, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
 pub struct MarginConfig {
     #[serde(default)]
     pub bottom: i32,
@@ -156,6 +163,7 @@ pub struct MarginConfig {
 /// depending on your [use-case](#2-pick-your-use-case).
 ///
 #[derive(Debug, Deserialize, Clone)]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
 pub struct BarConfig {
     /// A unique identifier for the bar, used for controlling it over IPC.
     /// If not set, uses a generated integer suffix.
@@ -292,6 +300,7 @@ impl Default for BarConfig {
 }
 
 #[derive(Debug, Deserialize, Clone, Default)]
+#[cfg_attr(feature = "schema", derive(JsonSchema))]
 pub struct Config {
     /// A map of [ironvar](ironvar) keys and values
     /// to initialize Ironbar with on startup.

src/config/truncate.rs

@@ -4,6 +4,7 @@ use serde::Deserialize;
 
 #[derive(Debug, Deserialize, Clone, Copy)]
 #[serde(rename_all = "snake_case")]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 pub enum EllipsizeMode {
     Start,
     Middle,
@@ -28,6 +29,7 @@ impl From<EllipsizeMode> for GtkEllipsizeMode {
 ///
 #[derive(Debug, Deserialize, Clone, Copy)]
 #[serde(untagged)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 pub enum TruncateMode {
     /// Auto mode lets GTK decide when to ellipsize.
     ///

src/dynamic_value/dynamic_bool.rs

@@ -8,6 +8,7 @@ use tokio::sync::mpsc;
 
 #[derive(Debug, Deserialize, Clone)]
 #[serde(untagged)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 pub enum DynamicBool {
     /// Either a script or variable, to be determined.
     Unknown(String),

src/main.rs

@@ -76,6 +76,13 @@ fn main() {
 fn run_with_args() {
     let args = cli::Args::parse();
 
+    #[cfg(feature = "schema")]
+    if args.print_schema {
+        let schema = schemars::schema_for!(Config);
+        println!("{}", serde_json::to_string_pretty(&schema).unwrap());
+        return;
+    }
+
     match args.command {
         Some(command) => {
             let rt = create_runtime();

src/modules/cairo.rs

@@ -18,6 +18,7 @@ use tokio::time::sleep;
 use tracing::{debug, error};
 
 #[derive(Debug, Clone, Deserialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 pub struct CairoModule {
     /// The path to the Lua script to load.
     /// This can be absolute, or relative to the working directory.

src/modules/clipboard.rs

@@ -17,6 +17,7 @@ use tokio::sync::{broadcast, mpsc};
 use tracing::{debug, error};
 
 #[derive(Debug, Deserialize, Clone)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
 pub struct ClipboardModule {
     /// The icon to show on the bar widget button.
     /// Supports [image](images) icons.