feat: common module options (show_if, on_click, tooltip)

The first three of many options that are common to all modules.

Resolves #36. Resolves partially #34.

docs/Configuration guide.md

@@ -1,6 +1,12 @@
 By default, you get a single bar at the bottom of all your screens.
 To change that, you'll unsurprisingly need a config file.
 
+This page details putting together the skeleton for your config to get you to a stage where you can start configuring modules.
+It may look long and overwhelming, but that is just because the bar supports a lot of scenarios! 
+
+If you want to see some ready-to-go config files check the [examples folder](https://github.com/JakeStanger/ironbar/tree/master/examples) 
+and the example pages in the sidebar.
+
 ## 1. Create config file
 
 The config file lives inside the `ironbar` directory in your XDG_CONFIG_DIR, which is usually `~/.config/ironbar`.
@@ -253,8 +259,11 @@ monitors:
 
 Once you have the basic config structure set up, it's time to actually configure your bar(s).
 
-The following table describes each of the top-level bar config options. 
-For details on available modules and each of their config options, check the sidebar.
+Check [here](config) for an example config file for a fully configured bar in each format.
+
+### 3.1 Top-level options
+
+The following table lists each of the top-level bar config options:
 
 | Name              | Type                                   | Default  | Description                                                                             |
 |-------------------|----------------------------------------|----------|-----------------------------------------------------------------------------------------|
@@ -265,4 +274,15 @@ For details on available modules and each of their config options, check the sid
 | `center`          | `Module[]`                             | `[]`     | Array of center modules.                                                                |
 | `end`             | `Module[]`                             | `[]`     | Array of right or bottom modules.                                                       |
 
-Check [here](config) for an example config file for a fully configured bar in each format.
+### 3.2 Module-level options
+
+The following table lists each of the module-level options that are present on **all** modules.
+For details on available modules and each of their config options, check the sidebar.
+
+For information on the `Script` type, see [here](script).
+
+| Name       | Type               | Default | Description                                                                                                        |
+|------------|--------------------|---------|--------------------------------------------------------------------------------------------------------------------|
+| `show_if`  | `Script [polling]` | `null`  | Polls the script to check its exit code. If exit code is zero, the module is shown. For other codes, it is hidden. |
+| `on_click` | `Script [polling]` | `null`  | Runs the script when the module is clicked.                                                                        |
+| `tooltip`  | `string`           | `null`  | Shows this text on hover.                                                                                          |

docs/Scripts.md

@@ -0,0 +1,91 @@
+There are various places inside the configuration (other than the `script` module)
+that allow script input to dynamically set values.
+
+Scripts are passed to `sh -c`.
+
+Two types of scripts exist: polling and watching:
+
+- Polling scripts will run and wait for exit.
+  Normally they will repeat this at an interval, hence the name, although in some cases they may only run on a user
+  event.
+  If the script exited code 0, the `stdout` will be used. Otherwise, `stderr` will be printed to the log.
+- Watching scripts start a long-running process. Every time the process writes to `stdout`, the last line is captured
+  and used.
+
+One should prefer to use watch-mode where possible, as it removes the overhead of regularly spawning processes.
+That said, there are some cases which only support polling. These are indicated by `Script [polling]` as the option
+type.
+
+## Writing script configs
+
+There are two available config formats for scripts, shorthand as a string, or longhand as an object.
+Shorthand can be used in all cases, but there are some cases (such as embedding scripts inside strings) where longhand
+cannot be used.
+
+In both formats, `mode` is one of `poll` or `watch` and `interval` is the number of milliseconds to wait between
+spawning the script.
+
+Both `mode` and `interval` are optional and can be excluded to fall back to their defaults of `poll` and `5000`
+respectively.
+
+### Shorthand (string)
+
+Shorthand scripts should be written in the format:
+
+```
+mode:interval:script
+```
+
+For example:
+
+```
+poll:5000:uptime -p | cut -d ' ' -f2-
+```
+
+### Longhand (object)
+
+An object consisting of the `cmd` key and optionally the `mode` and/or `interval` keys.
+
+<details>
+<summary>JSON</summary>
+
+```json
+{
+  "mode": "poll",
+  "interval": 5000,
+  "cmd": "uptime -p | cut -d ' ' -f2-"
+}
+```
+</details>
+
+<details>
+<summary>YAML</summary>
+
+```yaml
+mode: poll
+interval: 5000
+cmd: "uptime -p | cut -d ' ' -f2-"
+```
+</details>
+
+<details>
+<summary>YAML</summary>
+
+```toml
+mode = "poll"
+interval = 5000
+cmd = "uptime -p | cut -d ' ' -f2-"
+```
+</details>
+
+<details>
+<summary>Corn</summary>
+
+```corn
+{
+  mode = "poll"
+  interval = 5000
+  cmd = "uptime -p | cut -d ' ' -f2-"
+}
+```
+</details>

docs/_Sidebar.md

@@ -1,6 +1,7 @@
 # Guides
 
 - [Configuration guide](configuration-guide)
+  - [Scripts](scripts)
 - [Styling guide](styling-guide)
 
 # Examples