From b577e1eae356fe9ddc8c573ccb7b288170b3403c Mon Sep 17 00:00:00 2001
From: jzbor <jzbor@posteo.net>
Date: Tue, 7 Nov 2023 22:10:44 +0100
Subject: [PATCH] Adding mdBook documentation

---
 .github/workflows/docs-github-pages.yml       | 32 +++++++--
 book.toml                                     | 13 ++++
 docs/.gitignore                               |  1 +
 docs/SUMMARY.md                               | 12 ++++
 docs/configuration.md                         |  1 +
 docs/examples.md                              | 19 +++++
 docs/examples/mars-status.md                  | 13 ++++
 docs/examples/touchegg.md                     |  5 ++
 docs/examples/wallpaper-daemon.md             |  9 +++
 docs/examples/xdg-xmenu.md                    |  9 +++
 INSTALLATION.md => docs/installation.md       |  0
 docs/introduction.md                          |  3 +
 docs/marsbar.md                               | 71 +++++++++++++++++++
 marswm/src/docs/README.md => docs/marswm.md   |  0
 .../docs/QUICKSTART.md => docs/quickstart.md  | 25 +++----
 marsbar/README.md                             | 71 -------------------
 marswm/README.md                              |  4 +-
 marswm/src/docs/mod.rs                        |  3 -
 marswm/src/docs/quick_start.rs                |  1 -
 marswm/src/main.rs                            |  2 -
 20 files changed, 194 insertions(+), 100 deletions(-)
 create mode 100644 book.toml
 create mode 100644 docs/.gitignore
 create mode 100644 docs/SUMMARY.md
 create mode 100644 docs/configuration.md
 create mode 100644 docs/examples.md
 create mode 100644 docs/examples/mars-status.md
 create mode 100644 docs/examples/touchegg.md
 create mode 100644 docs/examples/wallpaper-daemon.md
 create mode 100644 docs/examples/xdg-xmenu.md
 rename INSTALLATION.md => docs/installation.md (100%)
 create mode 100644 docs/introduction.md
 create mode 100644 docs/marsbar.md
 rename marswm/src/docs/README.md => docs/marswm.md (100%)
 rename marswm/src/docs/QUICKSTART.md => docs/quickstart.md (82%)
 delete mode 100644 marswm/src/docs/mod.rs
 delete mode 100644 marswm/src/docs/quick_start.rs

diff --git a/.github/workflows/docs-github-pages.yml b/.github/workflows/docs-github-pages.yml
index 0e91442d..c3927c4c 100644
--- a/.github/workflows/docs-github-pages.yml
+++ b/.github/workflows/docs-github-pages.yml
@@ -12,6 +12,19 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: 'latest'
+      - run: mdbook build .
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: './target/book'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2
+
       - name: Install X11 dependencies
         uses: awalsh128/cache-apt-pkgs-action@latest
         with:
@@ -25,8 +38,8 @@ jobs:
         with:
           command: doc
           args: --no-deps
-      - name: Create forwarding to actual index.html
-        run: echo '<meta http-equiv="refresh" content="0; url=marswm">' > ./target/doc/index.html
+      # - name: Create forwarding to actual index.html
+      #   run: echo '<meta http-equiv="refresh" content="0; url=marswm">' > ./target/doc/index.html
       - name: Fix file permissions
         shell: sh
         run: |
@@ -34,12 +47,21 @@ jobs:
           while read line; do
           echo "::warning title=Invalid file permissions automatically fixed::$line"
           done
-      - name: Setup Pages
-        uses: actions/configure-pages@v3
+
+      - name: Copy stuff around
+        shell: sh
+        run:
+          mkdir output
+          cp -r target/book output/
+          cp -r target/doc output/crate
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v1
         with:
-          path: './target/doc'
+          path: './output'
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v2
+
diff --git a/book.toml b/book.toml
new file mode 100644
index 00000000..7a359cc3
--- /dev/null
+++ b/book.toml
@@ -0,0 +1,13 @@
+[book]
+authors = ["jzbor"]
+language = "en"
+multilingual = false
+src = "docs"
+title = "MARSWM Documentation"
+
+[build]
+build-dir = "target/book"
+
+[output.html]
+default-theme = "rust"
+preferred-dark-theme = "ayu"
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 00000000..7585238e
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
new file mode 100644
index 00000000..3821cb72
--- /dev/null
+++ b/docs/SUMMARY.md
@@ -0,0 +1,12 @@
+# Summary
+- [Introduction](introduction.md)
+- [Installation](./installation.md)
+- [Quick Start](./quickstart.md)
+- [Configuration](./configuration.md)
+	- [marswm](./marswm.md)
+	- [marsbar](./marswm.md)
+- [Examples](./examples.md)
+	- [mars-status.sh](examples/mars-status.md)
+	- [touchegg.conf](examples/touchegg.md)
+	- [wallpaper-daemon.sh](examples/wallpaper-daemon.md)
+	- [xdg-xmenu.py](examples/xdg-xmenu.md)
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 00000000..a025a48b
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1 @@
+# Configuration
diff --git a/docs/examples.md b/docs/examples.md
new file mode 100644
index 00000000..8b51bd1b
--- /dev/null
+++ b/docs/examples.md
@@ -0,0 +1,19 @@
+# Examples
+This chapter contains a couple of example scripts and configurations.
+All examples are available on [Github](https://github.com/jzbor/marswm/tree/master/examples).
+
+## Installing Configurations
+Most config files go into `~/.config/<program>/<program>.<suffix>`.
+For example marswm's main config goes into `~/.config/marswm/marswm.yaml`.
+
+## Installing Scripts
+To install a script you will first need to install all of its dependencies.
+
+Then place the script into a directory that is listed in your `$PATH`.
+It is suggested to use `~/.local/bin/` to store all of your personal scripts.
+You can check if that is in your path with `echo $PATH` and add it to your `~/.profile` otherwise.
+
+You will also have to make the script executable:
+```sh
+chmod +x <script>
+```
diff --git a/docs/examples/mars-status.md b/docs/examples/mars-status.md
new file mode 100644
index 00000000..75c80e4a
--- /dev/null
+++ b/docs/examples/mars-status.md
@@ -0,0 +1,13 @@
+# `mars-status.sh`
+
+Dependencies:
+* `canberra-gtk-play` ([`libcanberra-gtk3`](https://pkgs.org/search/?q=libcanberra-gtk3))
+* `notify-send` ([`libnotify`](https://pkgs.org/search/?q=libnotify))
+* `powerprofilesctl` ([`power-profiles-daemon`](https://pkgs.org/search/?q=power-profiles-daemon))
+* `pactl` ([`pulseaudio`](https://pkgs.org/search/?q=pulseaudio))
+* `xmenu` ([`xmenu`](https://github.com/phillbush/xmenu))
+
+```sh
+{{#include ../../examples/mars-status.sh}}
+```
+
diff --git a/docs/examples/touchegg.md b/docs/examples/touchegg.md
new file mode 100644
index 00000000..a9341609
--- /dev/null
+++ b/docs/examples/touchegg.md
@@ -0,0 +1,5 @@
+# `touchegg.conf`
+
+```xml
+{{#include ../../examples/touchegg.xml}}
+```
diff --git a/docs/examples/wallpaper-daemon.md b/docs/examples/wallpaper-daemon.md
new file mode 100644
index 00000000..f024f436
--- /dev/null
+++ b/docs/examples/wallpaper-daemon.md
@@ -0,0 +1,9 @@
+# `wallpaper-daemon`
+
+Dependencies:
+* `xev`
+* `xwallpaper`
+
+```sh
+{{#include ../../examples/wallpaper-daemon.sh}}
+```
diff --git a/docs/examples/xdg-xmenu.md b/docs/examples/xdg-xmenu.md
new file mode 100644
index 00000000..586b508c
--- /dev/null
+++ b/docs/examples/xdg-xmenu.md
@@ -0,0 +1,9 @@
+# `xdg-xmenu.py`
+
+Dependencies:
+* `python3`
+* `imagemagick`
+
+```py
+{{#include ../../examples/xdg-xmenu.py}}
+```
diff --git a/INSTALLATION.md b/docs/installation.md
similarity index 100%
rename from INSTALLATION.md
rename to docs/installation.md
diff --git a/docs/introduction.md b/docs/introduction.md
new file mode 100644
index 00000000..ba9f7e55
--- /dev/null
+++ b/docs/introduction.md
@@ -0,0 +1,3 @@
+# Introduction
+
+{{#include ../marswm/README.md}}
diff --git a/docs/marsbar.md b/docs/marsbar.md
new file mode 100644
index 00000000..735fa5ca
--- /dev/null
+++ b/docs/marsbar.md
@@ -0,0 +1,71 @@
+The configuration should be stored in the [YAML](https://yaml.org/) format at  `~/.config/marswm/marsbar.yaml`
+You can get the default configuration with `marsbar --print-default-config`.
+
+## The Status Script
+You can set the status on the right side of the bar with a custom skript or program.
+On X11 it uses the custom property `_MARS_STATUS` on the root window.
+You can use any program to set it, but `mars-relay` also supports the `set-status` command:
+```sh
+mars-relay set-status "Today is $(date +%F)"
+```
+
+You also have the possibility to use multiple **modules** for different metrics.
+They are separated by a special character, the default is currently `0x1f`.
+In a shell script you could use it like so:
+```sh
+load="$(cut -d' ' -f1 /proc/load)"
+date="$(date +%F)"
+status="$(printf "%s\x1f%s" "load: $load" "date: $date")"
+mars-relay set-status "$status"
+```
+
+The script/program is expected to update the status on its own.
+It can either be started by your own startup scripts/systemd/etc. or by `marsbar` itself.
+To launch the script with `marsbar` you have to make sure the script is executable (`chmod +x`).
+Then you can add it to the config file under the option `status_cmd`.
+
+### Button Actions
+`marsbar` also lets you handle button clicks for those status blocks.
+These are handled by a script/program which can be a different executable or just the same as used for status updates.
+Place the path to the executable under the `action_cmd` option in the config file.
+
+When a button is pressed that executable is called with the environment variables `BLOCK` and `BUTTON` are set:
+* `$BLOCK` contains the index of the status block that was clicked
+* `$BUTTON` contains the index number of the mouse button that generated the event
+
+
+## Theming
+Theming is available under the `style` subsection in the configuration file.
+
+This section might look something like this:
+```yaml
+style:
+  background: 0x262626             # background color of the bar
+  expand_workspace_widgets: false  # make all workspace widgets the same width
+  height: 31                       # height of the whole bar
+  font: FiraCode:size=12           # font of text surfaces (as xft name)
+  workspaces:
+    foreground: 0x262626           # foreground (text) color of the workspace widget
+    inner_background: 0x5F87AF     # background of the individual workspaces
+    outer_background: 0x262626     # background *around* the individual workspaces
+    padding_horz: 0                # horizontal padding around the workspaces
+    padding_vert: 0                # vertical padding around the workspaces
+    text_padding_horz: 10          # horizontal padding around the text
+    text_padding_vert: 4           # vertical padding around the text
+    spacing: 0                     # spacing between the individual workspaces
+  title:
+    foreground: 0xBCBCBC           # foreground (text) color
+    background: 0x262626           # background color of the text widget
+  status:
+    foreground: 0x262626           # foreground (text) color
+    inner_background: 0xAF5F5F     # background of the individual blocks
+    outer_background: 0x262626     # background *around* the individual blocks
+    padding_horz: 4                # horizontal padding around the blocks
+    padding_vert: 4                # vertical padding around the blocks
+    text_padding_horz: 5           # horizontal padding around the text
+    text_padding_vert: 0           # vertical padding around the text
+    spacing: 4                     # spacing between the individual blocks
+```
+
+*Note: Although they may look very weird in the output of `marsbar --print-default-config` colors can simply be written as hex values (like `0x1a2b3c`).*
+
diff --git a/marswm/src/docs/README.md b/docs/marswm.md
similarity index 100%
rename from marswm/src/docs/README.md
rename to docs/marswm.md
diff --git a/marswm/src/docs/QUICKSTART.md b/docs/quickstart.md
similarity index 82%
rename from marswm/src/docs/QUICKSTART.md
rename to docs/quickstart.md
index a17171e2..26349dd6 100644
--- a/marswm/src/docs/QUICKSTART.md
+++ b/docs/quickstart.md
@@ -1,10 +1,9 @@
 # Quick Start Guide
 This guide shows you how to build a fully functional desktop environment with marswm.
 
-
 ## Assumptions
 There are a few assumptions made in these scripts with regards to your system in this guide and in the scripts:
-* `marswm`, `marsbar` and `mars-relay` are already installed (see [`INSTALLATION.md`](./INSTALLATION.md))
+* `marswm`, `marsbar` and `mars-relay` are already installed (see ["Installation"](/installation.html))
 * You use either [PulseAudio](https://www.freedesktop.org/wiki/Software/PulseAudio/) or [pipewire](https://pipewire.org/) with `pactl` installed (probably in the `pulseaudio` package)
 * Your distro uses [systemd](https://systemd.io/)
 
@@ -36,14 +35,8 @@ We will add further lines to this script later on.
 ## Status Script
 `marsbar` can use scripts to display status information and generate menus.
 
-An example script is provided in the marswm repo to get you started.
-You can simply install the [`mars-status`](examples/mars-status.sh) script into your `$PATH` (e.g. `~/.local/bin/mars-status`) and make it executable (`chmod +x mars-status`).
-You will also have to make sure to have the following dependencies installed:
-* `canberra-gtk-play` ([`libcanberra-gtk3`](https://pkgs.org/search/?q=libcanberra-gtk3))
-* `notify-send` ([`libnotify`](https://pkgs.org/search/?q=libnotify))
-* `powerprofilesctl` ([`power-profiles-daemon`](https://pkgs.org/search/?q=power-profiles-daemon))
-* `pactl` ([`pulseaudio`](https://pkgs.org/search/?q=pulseaudio))
-* `xmenu` ([`xmenu`](https://github.com/phillbush/xmenu))
+You can find an example script [`mars-status`](/examples/mars-status.html) in examples section.
+Read [Examples/Installing Scripts](examples.html#installing-scripts) for more information on how to install it.
 
 Now you can add the script to your `marsbar` config in `~/.config/marswm/marsbar.yaml`:
 ```yaml
@@ -53,10 +46,10 @@ action_cmd: "mars-status action"
 
 
 ## Wallpaper
-This repo also contains a simple script to set your wallpaper: [`wallpaper-daemon`](examples/wallpaper-daemon.sh).
+This repo also contains a simple script to set your wallpaper: [`wallpaper-daemon`](examples/wallpaper-daemon.md).
 It automatically adjusts your wallpaper whenever your screen configuration changes.
-Make sure to install its dependencies `xev` and `xwallpaper`.
-Add it to your `$PATH` (e.g. `~/.local/bin/wallpaper-daemon`) and make it executable (`chmod +x wallpaper-daemon`).
+Read [Examples/Installing Scripts](examples.html#installing-scripts) for more information on how to install it.
+
 
 Now we can add it to our autostart script:
 ```sh
@@ -67,8 +60,8 @@ It will load whatever wallpaper you put in `~/.background-image`.
 
 
 ## Application Menu(s)
-Another script provided in `examples/` is [`xdg-xmenu.py`](examples/xdg-xmenu.py).
-Put it in your `$PATH` (e.g. `~/.local/bin/xdg-xmenu`) and make it executable.
+Another script provided in `examples/` is [`xdg-xmenu.py`](examples/xdg-xmenu.md).
+Read [Examples/Installing Scripts](examples.html#installing-scripts) for more information on how to install it.
 
 Now we can add it to our button bindings.
 It is suggested to put it in `~/.config/marswm/buttonbindings_ext.yaml` as this way it does not interfere with other default bindings:
@@ -143,7 +136,7 @@ You may want to test this once to make sure everything works.
 
 
 ## Touch Gestures
-There is an [example config](examples/touchegg.xml) for [Touchégg](https://github.com/JoseExposito/touchegg) provided along with this repo.
+There is an [example config](examples/touchegg.md) for [Touchégg](https://github.com/JoseExposito/touchegg) provided along with this repo.
 Copy the file to `~/.config/touchegg/touchegg.conf`.
 Then [install and setup](https://github.com/JoseExposito/touchegg#installation) touchegg (it requires a server daemon to run, as well as a client).
 
diff --git a/marsbar/README.md b/marsbar/README.md
index 4d2578fc..27209d52 100644
--- a/marsbar/README.md
+++ b/marsbar/README.md
@@ -2,74 +2,3 @@
 
 `marsbar` is a minimalist status bar for `marswm` and other X11/EWMH Window Managers.
 
-The configuration should be stored in the [YAML](https://yaml.org/) format at  `~/.config/marswm/marsbar.yaml`
-You can get the default configuration with `marsbar --print-default-config`.
-
-## The Status Script
-You can set the status on the right side of the bar with a custom skript or program.
-On X11 it uses the custom property `_MARS_STATUS` on the root window.
-You can use any program to set it, but `mars-relay` also supports the `set-status` command:
-```sh
-mars-relay set-status "Today is $(date +%F)"
-```
-
-You also have the possibility to use multiple **modules** for different metrics.
-They are separated by a special character, the default is currently `0x1f`.
-In a shell script you could use it like so:
-```sh
-load="$(cut -d' ' -f1 /proc/load)"
-date="$(date +%F)"
-status="$(printf "%s\x1f%s" "load: $load" "date: $date")"
-mars-relay set-status "$status"
-```
-
-The script/program is expected to update the status on its own.
-It can either be started by your own startup scripts/systemd/etc. or by `marsbar` itself.
-To launch the script with `marsbar` you have to make sure the script is executable (`chmod +x`).
-Then you can add it to the config file under the option `status_cmd`.
-
-### Button Actions
-`marsbar` also lets you handle button clicks for those status blocks.
-These are handled by a script/program which can be a different executable or just the same as used for status updates.
-Place the path to the executable under the `action_cmd` option in the config file.
-
-When a button is pressed that executable is called with the environment variables `BLOCK` and `BUTTON` are set:
-* `$BLOCK` contains the index of the status block that was clicked
-* `$BUTTON` contains the index number of the mouse button that generated the event
-
-
-## Theming
-Theming is available under the `style` subsection in the configuration file.
-
-This section might look something like this:
-```yaml
-style:
-  background: 0x262626             # background color of the bar
-  expand_workspace_widgets: false  # make all workspace widgets the same width
-  height: 31                       # height of the whole bar
-  font: FiraCode:size=12           # font of text surfaces (as xft name)
-  workspaces:
-    foreground: 0x262626           # foreground (text) color of the workspace widget
-    inner_background: 0x5F87AF     # background of the individual workspaces
-    outer_background: 0x262626     # background *around* the individual workspaces
-    padding_horz: 0                # horizontal padding around the workspaces
-    padding_vert: 0                # vertical padding around the workspaces
-    text_padding_horz: 10          # horizontal padding around the text
-    text_padding_vert: 4           # vertical padding around the text
-    spacing: 0                     # spacing between the individual workspaces
-  title:
-    foreground: 0xBCBCBC           # foreground (text) color
-    background: 0x262626           # background color of the text widget
-  status:
-    foreground: 0x262626           # foreground (text) color
-    inner_background: 0xAF5F5F     # background of the individual blocks
-    outer_background: 0x262626     # background *around* the individual blocks
-    padding_horz: 4                # horizontal padding around the blocks
-    padding_vert: 4                # vertical padding around the blocks
-    text_padding_horz: 5           # horizontal padding around the text
-    text_padding_vert: 0           # vertical padding around the text
-    spacing: 4                     # spacing between the individual blocks
-```
-
-*Note: Although they may look very weird in the output of `marsbar --print-default-config` colors can simply be written as hex values (like `0x1a2b3c`).*
-
diff --git a/marswm/README.md b/marswm/README.md
index 927ebb94..928297b4 100644
--- a/marswm/README.md
+++ b/marswm/README.md
@@ -7,7 +7,7 @@ The [YAML](https://yaml.org/) format is used for configuration with the default
 You can get the default configuration with `marswm --print-default-config`.
 
 ## Documentation
-[https://jzbor.de/marswm/marswm/docs/index.html]
+[You can find the documentation here](https://jzbor.de/marswm/marswm/docs/index.html)
 
 ## Quick Start Guide
-[https://jzbor.de/marswm/marswm/docs/quick_start/index.html]
+[You can find the documentation here](https://jzbor.de/marswm/marswm/docs/index.html)
diff --git a/marswm/src/docs/mod.rs b/marswm/src/docs/mod.rs
deleted file mode 100644
index b6038a89..00000000
--- a/marswm/src/docs/mod.rs
+++ /dev/null
@@ -1,3 +0,0 @@
-#![doc = include_str!("./README.md")]
-
-mod quick_start;
diff --git a/marswm/src/docs/quick_start.rs b/marswm/src/docs/quick_start.rs
deleted file mode 100644
index b12ed7db..00000000
--- a/marswm/src/docs/quick_start.rs
+++ /dev/null
@@ -1 +0,0 @@
-#![doc = include_str!("./QUICKSTART.md")]
diff --git a/marswm/src/main.rs b/marswm/src/main.rs
index ec552f8b..5e835589 100644
--- a/marswm/src/main.rs
+++ b/marswm/src/main.rs
@@ -1,6 +1,5 @@
 #![doc = include_str!("../README.md")]
 
-
 use clap::Parser;
 use libmars::utils::configuration::*;
 use libmars::wm::*;
@@ -17,7 +16,6 @@ use crate::marswm::*;
 mod attributes;
 mod bindings;
 mod config;
-mod docs;
 mod layouts;
 mod macros;
 mod marswm;