WIP document configuration

config/config.dhall

@@ -6,43 +6,94 @@ let Margin = Vector2 Natural
 
 let FSPath = { name : Text, path : Text }
 
-let TextGeo = { Type = { text_spacing : Natural }, default.text_spacing = 20 }
+let TextGeo =
+    {-
+    Defines text dimensions for multiline visuals
 
-let SepGeo = { Type = { sep_spacing : Natural }, default.sep_spacing = 20 }
+    text_spacing: gap between lines of text
+    -}
+      { Type = { text_spacing : Natural }, default.text_spacing = 20 }
+
+let SepGeo =
+    {-
+    Defines separator dimensions
+
+    sep_spacing: gap between the separator and either above or below
+    -}
+      { Type = { sep_spacing : Natural }, default.sep_spacing = 20 }
 
 let PlotGeo =
+    {-
+    Defines plot dimensions
+
+    sec_break: gap between the plot label and the plot itself
+    height: height of the plot (without the label)
+    ticks_y: number of ticks on the y axis
+    -}
       { Type = { sec_break : Natural, height : Natural, ticks_y : Natural }
       , default = { sec_break = 20, height = 56, ticks_y = 4 }
       }
 
 let PlotGeo_ = { Type = { plot : PlotGeo.Type }, default.plot = PlotGeo::{=} }
 
-let TableGeo = { Type = { sec_break : Natural }, default.sec_break = 20 }
+let TableGeo =
+    {-
+    Defines table dimensions
+
+    sec_break: spacing between header and the first table row
+    -}
+      { Type = { sec_break : Natural }, default.sec_break = 20 }
 
 let TableGeo_ =
       { Type = { table : TableGeo.Type }, default.table = TableGeo::{=} }
 
 let FSGeo =
+    {-
+    Defines Filesystem module dimensions
+
+    bar_spacing: spacing between percent usage bars
+    bar_pad: spacing between usage bars and the left edge of the panel
+    -}
       { Type = { bar_spacing : Natural, bar_pad : Natural } //\\ SepGeo.Type
       , default = { bar_spacing = 20, bar_pad = 100 } /\ SepGeo::{=}
       }
 
 let GfxGeo =
+    {-
+    Defines Graphics module dimensions
+
+    See PlotGeo, TextGeo, and SepGeo for options included here
+    -}
       { Type = SepGeo.Type //\\ PlotGeo_.Type //\\ TextGeo.Type
       , default = SepGeo::{=} /\ PlotGeo_::{=} /\ TextGeo::{=}
       }
 
 let MemGeo =
+    {-
+    Defines Memory module dimensions
+
+    See PlotGeo, TextGeo, and TableGeo for options included here
+    -}
       { Type = TextGeo.Type //\\ PlotGeo_.Type //\\ TableGeo_.Type
       , default = TextGeo::{=} /\ PlotGeo_::{=} /\ TableGeo_::{=}
       }
 
 let ProcGeo =
+    {-
+    Defines Processor module dimensions
+
+    See GfxGeo and TableGeo for options included here
+    -}
       { Type = GfxGeo.Type //\\ TableGeo_.Type
       , default = GfxGeo::{=} /\ TableGeo_::{=}
       }
 
 let PwrGeo =
+    {-
+    Defines Processor module dimensions
+
+    See TextGeo and PlotGeo for options included here
+    -}
       { Type = TextGeo.Type //\\ PlotGeo_.Type
       , default = TextGeo::{=} /\ PlotGeo_::{=}
       }
@@ -51,6 +102,14 @@ let AllGeo =
       { TextGeo, PlotGeo, TableGeo, FSGeo, GfxGeo, MemGeo, ProcGeo, PwrGeo }
 
 let FileSystem =
+    {-
+    Defines Filesystem module configuration
+
+    show_smart: show SMART daemon indicator
+    show_seafile: show seafile daemon indicator
+    fs_paths: list of filesystem paths to monitor for percent usage
+    geometry: dimensional data for this module
+    -}
       { Type =
           { show_smart : Bool
           , show_seafile : Bool
@@ -61,6 +120,17 @@ let FileSystem =
       }
 
 let Graphics =
+    {-
+    Defines Graphics module configuration
+
+    dev_power: show a power indicator
+    show_temp: show temperature in celsius
+    show_clock: show clock speed
+    show_gpu_util: show percent utilization
+    show_mem_util: show percent memory utilized
+    show_vid_util: show percent video utilized
+    geometry: dimensional configuration for this module
+    -}
       { Type =
           { dev_power : Text
           , show_temp : Bool
@@ -74,6 +144,15 @@ let Graphics =
       }
 
 let Memory =
+    {-
+    Defines Memory module configuration
+
+    show_stats: show total memory gauge, cache, buffers, shared, and slab
+    show_plot: show memory utilization plot
+    show_swap: show swap utilization gauge (only if 'show_stats' is true)
+    table_rows: top processes by memory to display in table (max 10)
+    geometry: dimensional configuration for this module
+    -}
       { Type =
           { show_stats : Bool
           , show_plot : Bool
@@ -85,11 +164,33 @@ let Memory =
       }
 
 let Network =
+    {-
+    Defines Network module configuration
+
+    geometry: dimensional configuration for this module
+    -}
       { Type = { geometry : PlotGeo_.Type }, default.geometry = PlotGeo_::{=} }
 
-let CoreGroup = { threads : Natural, rows : Natural, padding : Natural }
+let CoreGroup =
+    {-
+    Defines a processor group for the Processor module
+
+    threads: the number of threads for each core in this group (usually 1 or 2)
+    rows: the number of rows over which to display the cores in this group
+    padding: the spacing to the left and right of the gauges in this group
+    -}
+      { threads : Natural, rows : Natural, padding : Natural }
 
 let Processor =
+    {-
+    Defines Network module configuration
+
+    core_groups: a list of core groups to display
+    show_stats: show frequency for each core group and HWP status
+    show_plot: show percent utilization plot
+    table_rows: top processes by cpu percent to display in table (max 10)
+    geometry: dimensional configuration for this module
+    -}
       { Type =
           { core_groups : List CoreGroup
           , show_stats : Bool
@@ -100,23 +201,53 @@ let Processor =
       , default.geometry = ProcGeo::{=}
       }
 
-let RaplSpec = { name : Text, address : Text }
-
 let Pacman =
+    {-
+    Defines Pacman module configuration
+
+    geometry: dimensional configuration for this module
+    -}
       { Type = { geometry : TextGeo.Type }, default.geometry = TextGeo::{=} }
 
+let RaplSpec =
+    {-
+    Defines a RAPL endpoint to display in the Power module
+
+    name: nice name to display above plot
+    address: sysfs address to the directory containing the 'energy_uj' file
+    -}
+      { name : Text, address : Text }
+
 let Power =
+    {-
+    Defines Power module configuration
+
+    battery: sysfs path to the battery to display
+    rapl_specs: list of RAPL endpoints to display
+    geometry: dimensional configuration for this module
+    -}
       { Type =
           { battery : Text, rapl_specs : List RaplSpec, geometry : PwrGeo.Type }
       , default.geometry = PwrGeo::{=}
       }
 
 let ReadWrite =
+    {-
+    Defines ReadWrite module configuration
+
+    geometry: dimensional configuration for this module
+    -}
       { Type = { devices : List Text, geometry : PlotGeo_.Type }
       , default.geometry = PlotGeo_::{=}
       }
 
-let System = Pacman
+let System =
+    {-
+    Defines System module configuration
+
+    geometry: dimensional configuration for this module
+    -}
+      Pacman
 
 let AllModules =
       { FileSystem
@@ -297,6 +428,14 @@ let Patterns =
       }
 
 let Theme =
+    {-
+    Defines the theme for displaying the window
+
+    font: the font to use
+    geometry: the global dimensions to use for each panel and widget (for
+              everything not define by individual modules)
+    patterns: colors and gradient definitions
+    -}
       { Type =
           { font : Font.Type
           , geometry : Geometry.Type

config/fallback.yml

@@ -1,83 +0,0 @@
-bootstrap:
-  update_interval: 1
-  dimensions: [1920, 1080]
-modules:
-  memory:
-    show_stats: false
-    show_swap: false
-    show_plot: true
-    table_rows: 3
-  processor:
-    core_rows: 0
-    core_padding: 0
-    show_stats: false
-    show_plot: true
-    table_rows: 3
-
-layout:
-  anchor: [12, 11]
-  panels:
-    - columns:
-        - {blocks: [network, 10, memory, 10, processor], width: 436}
-      margins: [20, 10]
-
-theme:
-  font:
-    family: Neuropolitical
-    sizes:
-      normal: 13
-      plot_label: 8
-      table: 11
-      header: 15
-  geometry:
-    plot:
-      seconds: 90
-      ticks: [9, 4]
-      height: 56
-      spacing: 20
-    table:
-      name_chars: 8
-      padding: [6, 15]
-      header_padding: 20
-      row_spacing: 13
-    header:
-      underline_offset: 26
-      padding: 19
-  patterns:
-    header: 0xefefef
-    panel:
-      bg: {color: 0x121212, alpha: 0.7}
-    text:
-      active: 0xbfe1ff
-      inactive: 0xc8c8c8
-      critical: 0xff8282
-    border: 0x888888
-    plot:
-      grid: 0x666666
-      outline: 0x777777
-      data:
-        border: 
-          gradient:
-            - {stop: 0, color: 0x003f7c}
-            - {stop: 1, color: 0x1e90ff}
-        fill:
-          gradient_alpha:
-            - {stop: 0.2, color: 0x316ece, alpha: 0.5}
-            - {stop: 1, color: 0x8cc7ff, alpha: 1.0}
-    indicator:
-      bg:
-        gradient:
-          - {stop: 0, color: 0x565656}
-          - {stop: 0.5, color: 0xbfbfbf}
-          - {stop: 1, color: 0x565656}
-      fg:
-        active:
-          gradient:
-            - {stop: 0, color: 0x316BA6}
-            - {stop: 0.5, color: 0x99CEFF}
-            - {stop: 1, color: 0x316BA6}
-        critical:
-          gradient:
-            - {stop: 0, color: 0xFF3333}
-            - {stop: 0.5, color: 0xFFB8B8}
-            - {stop: 1, color: 0xFF3333}

config/schema.yml

@@ -1,375 +0,0 @@
-$schema: "http://json-schema.org/draft-07/schema#"
-description: over-engineered conky schema
-required: [modules, layout]
-additionalProperties: false
-properties:
-
-  bootstrap:
-    required: [update_interval, dimensions]
-    additionalProperties: false
-    properties:
-      update_interval:
-        description: the update interval (seconds)
-        type: number
-      dimensions:
-        description: the max width/height of the conky window
-        type: array
-        minItems: 2
-        maxItems: 2
-        items:
-          type: integer
-          minimum: 1
-
-  # NOTE none of these are required
-  modules:
-    additionalProperties: false
-    properties:
-      filesystem:
-        required: [show_smart, fs_paths]
-        additionalProperties: false
-        properties:
-          show_smart:
-            description: show the smart deamon indicator
-            type: boolean
-          fs_paths:
-            description: the filesystem paths for which usage should be shown
-            type: array
-            minItems: 1
-            items:
-              type: object
-              required: [name, path]
-              additionalProperties: false
-              properties:
-                name:
-                  type: string
-                path:
-                  type: string
-
-      graphics:
-        required: [show_temp, show_clock, show_gpu_util, show_mem_util, show_vid_util]
-        additionalProperties: false
-        properties:
-          dev_power:
-            description: the sysfs path to the graphics card power indicator
-            type: string
-          show_temp:
-            description: show the GPU temp
-            type: boolean
-          show_clock:
-            description: show the GPU clock speeds
-            type: boolean
-          show_gpu_util:
-            description: show the GPU utilization plot
-            type: boolean
-          show_mem_util:
-            description: show the GPU memory utilization plot
-            type: boolean
-          show_vid_util:
-            description: show the GPU video utilization plot
-            type: boolean
-
-      memory:
-        required: [show_stats, show_plot, table_rows]
-        additionalProperties: false
-        properties:
-          show_stats:
-            description: show memory stats/dial
-            type: boolean
-          show_swap:
-            description: show swap dial
-            type: boolean
-          show_plot:
-            description: show the RAM utilization plot
-            type: boolean
-          table_rows: &table
-            descrition: the number of rows in the table (0 for no table)
-            type: integer
-            minimum: 0
-
-      power:
-        required: [battery, rapl_specs]
-        additionalProperties: false
-        properties:
-          battery:
-            description: the battery device to use (or blank if none)
-            type: string
-          rapl_specs:
-            description: the Intel RAPL specs for which plots should be made
-            type: array
-            items:
-              type: object
-              required: [name, address]
-              additionalProperties: false
-              properties:
-                name:
-                  type: string
-                address:
-                  type: string
-
-      processor:
-        required: [core_rows, show_stats, show_plot, table_rows]
-        additionalProperties: false
-        properties:
-          core_rows:
-            description: the number of rows over which to show discrete cores
-            type: integer
-            minimum: 0
-          core_padding:
-            description: horizontal padding to apply to the core layout
-            type: integer
-            minimum: 0
-          show_stats:
-            description: show frequency/HWP stats
-            type: boolean
-          show_plot:
-            description: show CPU utilization plot
-            type: boolean
-          table_rows: *table
-
-      readwrite:
-        required: [devices]
-        additionalProperties: false
-        properties:
-          devices:
-            description: the devices to include in I/O summations
-            type: array
-            minItems: 1
-            items:
-              type: string
-
-  layout:
-    required: [anchor, panels]
-    additionalProperties: false
-    properties:
-      anchor:
-        description: the coordinates of the upper-left corner to anchor the app
-        type: array
-        minItems: 2
-        maxItems: 2
-        items:
-          type: integer
-      panels:
-        description: either a panel (object) or padding between panels (int)
-        type: array
-        items:
-          anyOf:
-            - type: integer
-              minimum: 0
-            - type: object
-              description: layout for a single panel
-              required: [columns, margins]
-              additionalProperties: false
-              properties:
-                margins:
-                  type: array
-                  minItems: 2
-                  maxItems: 2
-                  items:
-                    type: integer
-                columns:
-                  description: |
-                    either the columns in this panel (object) or padding
-                    between columns (int)
-                  type: array
-                  minItems: 1
-                  items:
-                    anyOf:
-                      - type: integer
-                        minimum: 0
-                      - type: object
-                        required: [blocks, width]
-                        additionalProperties: false
-                        properties:
-                          width:
-                            description: the width of all modules in this column
-                            type: integer
-                            minimum: 0
-                          blocks:
-                            description: |
-                              either a module name (string) or padding (int)
-                            type: array
-                            minItems: 1
-                            items:
-                              anyOf:
-                                - type: integer
-                                  minimum: 0
-                                - type: string
-                                  pattern:
-                                    "^system|graphics|processor|readwrite|\
-                                    network|pacman|filesystem|power|memory$"
-
-  theme:
-    required: [font, geometry, patterns]
-    additionalProperties: false
-    properties:
-      font:
-        required: [family, sizes]
-        additionalProperties: false
-        properties:
-          family:
-            type: string
-          sizes:
-            required: [normal, plot_label, table, header]
-            additionalProperties: false
-            properties:
-              normal: &font_size
-                type: integer
-                minimum: 5
-              plot_label: *font_size
-              table: *font_size
-              header: *font_size
-
-      geometry:
-        required: [plot, table]
-        additionalProperties: false
-        properties:
-          plot:
-            required: [seconds, ticks, height, spacing]
-            additionalProperties: false
-            properties:
-              spacing:
-                description: the spacing between the label and the plot
-                type: integer
-                minimum: 10
-              height:
-                description: the height of the plot
-                type: integer
-                minimum: 10
-              seconds:
-                description: the number of seconds on each timeseries plot
-                type: integer
-                minimum: 30
-              ticks:
-                description: the number of ticks on the x/y axes
-                type: array
-                minItems: 2
-                maxItems: 2
-                items:
-                  type: integer
-                  minimum: 2
-          table:
-            required: [name_chars, padding, header_padding]
-            additionalProperties: false
-            properties:
-              name_chars:
-                description: |
-                  the length to which the name column should be trimmed (if any)
-                type: integer
-                minimum: 0
-              padding:
-                description: the x/y padding around the table
-                type: array
-                minItems: 2
-                maxItems: 2
-                items:
-                  type: integer
-                  minimum: 0
-              header_padding:
-                description: the padding beneath the column headers
-                type: integer
-                minimum: 0
-              row_spacing:
-                description: the distance between the center of each row
-                type: integer
-                minimum: 10
-
-          header:
-            required: [underline_offset, padding]
-            additionalProperties: false
-            properties:
-              underline_offset:
-                description: the offset of the underline (from top of header)
-                type: integer
-                minimum: 10
-              padding:
-                description: the padding beneath the underline
-                type: integer
-                minimum: 0
-
-      patterns:
-        required: [header, panel, text, border, plot, indicator]
-        additionalProperties: false
-        properties:
-          header: &pattern
-            oneOf:
-              - type: integer
-              - type: object
-                oneOf:
-                  - required: [color, alpha]
-                  - required: [gradient]
-                  - required: [gradient_alpha]
-                properties:
-                  color:
-                    type: integer
-                    maximum: 0xffffff
-                  alpha: &alpha
-                    type: number
-                    minimum: 0
-                    maximum: 1
-                  gradient:
-                    type: array
-                    minItems: 2
-                    items:
-                      type: object
-                      required: [stop, color]
-                      additionalProperties: false
-                      properties: &gradient
-                        stop:
-                          type: number
-                          minimum: 0
-                          maximum: 1
-                        color:
-                          type: integer
-                          maximum: 0xffffff
-
-                  gradient_alpha:
-                    type: array
-                    minItems: 2
-                    items:
-                      type: object
-                      required: [stop, color, alpha]
-                      additionalProperties: false
-                      properties:
-                        <<: *gradient
-                        alpha: *alpha
-
-          panel:
-            required: [bg]
-            additionalProperties: false
-            properties:
-              bg: *pattern
-
-          text:
-            required: [active, inactive, critical]
-            additionalProperties: false
-            properties:
-              active: *pattern
-              inactive: *pattern
-              critical: *pattern
-
-          border: *pattern
-
-          plot:
-            required: [grid, outline, data]
-            additionalProperties: false
-            properties:
-              grid: *pattern
-              outline: *pattern
-              data:
-                required: [border, fill]
-                additionalProperties: false
-                properties:
-                  border: *pattern
-                  fill: *pattern
-
-          indicator:
-            required: [bg, fg]
-            additionalProperties: false
-            properties:
-              bg: *pattern
-              fg:
-                required: [active, critical]
-                additionalProperties: false
-                properties:
-                  active: *pattern
-                  critical: *pattern