Merge pull request #1 from rohrsben/config-rework

Config rework

Author: rohrsben

docs/.vitepress/config.mts

@@ -17,22 +17,12 @@ export default defineConfig({
     ],
 
     sidebar: [
-      { text: 'Introduction', link: '/introduction'},
       {
-        text: 'Wavewall',
+        text: 'Configuration',
         items: [
-          { text: 'Output', link: '/wavewall/output' },
-          { text: 'Generation', link: '/wavewall/generation' },
-        ],
-      },
-      {
-        text: 'Tileset',
-        items: [
-          { text: 'Info', link: '/tileset/info' },
-          { text: 'Selection', link: '/tileset/selection' },
-          { text: 'Pseudotiles', link: '/tileset/pseudotiles' },
-          { text: 'Recipes', link: 'tileset/recipes' },
-          { text: 'Colorizer', link: 'tileset/colorizer' },
+          { text: 'Output', link: '/configuration/output' },
+          { text: 'Tileset', link: '/configuration/tileset' },
+          { text: 'Colorizer', link: '/configuration/colorizer' }
         ],
       },
       {
@@ -56,6 +46,13 @@ export default defineConfig({
           { text: 'ColorInfo', link: '/userdata/colorinfo' },
         ],
       },
+      {
+        text: 'Other',
+        items: [
+          { text: 'Pseudotiles', link: '/other/pseudotiles' },
+          { text: 'Recipes', link: '/other/recipes' }
+        ],
+      }
     ],
 
     socialLinks: [

docs/configuration/colorizer.md

@@ -0,0 +1,69 @@
+---
+title: Colorizer
+---
+
+# About
+`colorizer` is a setting which allows you to recolor the pixels in the output image after it has been generated.
+
+You can do this by setting `colorizer` to either a function or a table.
+If you choose a function, that function will be run for every pixel in the output image. This might be what you want! But it can also be a bit slow. Choosing table allows you to create direct color-to-color conversions, which are much faster to execute. You are still able to choose if a color should be recolored using a function, so unless necessary, I would go for the table version.
+
+Whether you write one main function, or a function that only operates on one color, it will need to follow this spec:
+- *Input*: one parameter, a [`PixelInfo` object](/userdata/pixelinfo)
+- *Output*: one of:
+    - a hex code, like `"#FF0000"` or `"#FF0000FF"`
+    - a table with `r`, `g`, `b`, and `a` values. `a` is optional, and will default to `255`
+::: details Example
+```lua
+function (info)
+    -- interchanges the r, g, and b values
+    return {
+        r = info.g,
+        g = info.b,
+        b = info.r,
+        a = info.a
+    }
+end
+```
+:::
+
+## Ways to set
+### Table
+A `colorizer` table is a mapping from input color codes -- the left side of the equals sign -- to either another color code, or a function which follows the spec above. `colorizer.default` is treated specially: if this is set, any pixel which doesn't match a color code is fed to the `default`. This is probably most useful as a function, but you can set it to a color code as well if you like.
+
+::: details Example
+```lua
+colorizer = {
+    ["#000000"] = "#00FF00",
+    ["#FF0000"] = function (info)
+        -- function logic omitted
+        return hex_code
+    end,
+
+    default = function (info)
+        -- function logic omitted
+        return hex_code
+    end
+}
+```
+
+Here black pixels (`"#000000"`) will get mapped to green (`"#00FF00"`), red pixels (`"#FF0000"`) will be set to the result of a function, and everything else will be set to the result of a second function.
+:::
+::: details Tips and Info
+- The fields have to be set using the weird-looking `["#000000"]` because `#` means something in actual lua code. Doing it this way wraps it in a string.
+- If you have a color-code variable, perhaps imported from something like a `colorscheme.lua`, and you want to use it on the left side of the `=`, make sure to wrap it in brackets as well. This is not necessary on the right side. A la
+```lua
+local my_variable = "#00FF00"
+local other_var = "#0000FF"
+
+colorizer = {
+    [my_variable] = other_var
+}
+```
+Otherwise Wavewall will attempt to convert `"my_variable"` to a color and throw an error
+- You can include alpha values on both sides as well, for instance `"#FF0000FF"`
+
+:::
+### Function
+See the example used in the function spec above. Setting `colorizer` this way is essentially the same as setting `colorizer` to a table with only `default` defined.
+

docs/configuration/output.md

@@ -0,0 +1,67 @@
+---
+title: Output
+---
+
+# About
+The `output` section contains settings related to the output image, as well as some non-tileset-specific generation settings.
+
+## Fields
+
+### `directory` - nil, string
+The directory in which to save the generated image.
+::: details Nil
+If `directory` is nil, it defaults to the configuration directory.
+:::
+::: details String
+A fully expanded path.
+
+::: details Example
+`directory = "/home/<user>/directory"` (no trailing slash)
+:::
+
+### `filename` - nil, string
+What name to give the generated `.png` file.
+::: details Nil
+If `filename` is nil, it defaults to `result.png`.
+:::
+::: details String
+Any string that can be a valid filename on your operating system.
+::: details Example
+`filename = "save_file.png"`
+:::
+
+### `offset` - nil, bool
+Wavewall adds a small amount of offset to where it places the tiles, to create a bit of variance between generations. This setting allows you to disable that behaviour.
+
+::: details Example
+```lua
+offset = false
+```
+:::
+
+### `size` - table
+Specifies the dimensions of the output image.
+
+**Fields**:
+- `height` - positive number
+- `width` - positive number
+
+::: details Example
+```lua
+size = {
+    width = 1920,
+    height = 1080
+}
+```
+:::
+
+## Example
+```lua
+output = {
+    filename = "not_result.png",
+    directory = "/home/<user>/some/dir",
+    size = {
+        height = 50,
+        width = 1000
+    }
+}

docs/configuration/tileset.md

@@ -0,0 +1,78 @@
+---
+title: Tileset
+---
+
+# About
+The `tileset` section allows you to set which and how tiles should be stitched together.
+
+I recommend defining this in a `tileset.lua` file which is contained in the tileset directory, and then importing it into `wavewall.lua`. This allows tilesets to be easily shareable, and I think that would be really cool to see! But more importantly, the settings probably can't be reused across tilesets, so it makes sense to keep them self-contained.
+
+## Fields
+### `info` - table
+`info` is basically metadata for the tileset.
+
+**Fields**:
+- `name` - string
+
+This has to be the same as the tileset's folder
+- `tile_size` - nil, positive number
+
+For now, this is automatically inferred and doesn't need to be set. Stay tuned though!
+
+::: details Example
+```lua
+tileset = {
+    info = {
+        name = "my_tileset"
+    }
+}
+```
+:::
+
+### `pseudotiles` - nil, table
+See [Pseudotiles](/other/pseudotiles)
+
+::: details Example
+```lua
+tileset = {
+    pseudotiles = {
+        tile_a = {
+            pseudo_a = "90",
+            pseudo_b = "horizontal"
+        }
+    }
+}
+```
+:::
+
+### `recipe` - nil, string
+Allows you to specify a recipe to use.
+
+::: details Example
+```lua
+tileset = {
+    recipe = "some_recipe"
+}
+```
+:::
+
+### `recipes` - table
+See [Recipes](/other/recipes)
+
+::: details Example
+```lua
+tileset = {
+    recipes = {
+        recipe_a = {
+            tiles = {"tile_a", "tile_b"},
+        }
+        recipe_b = {
+            tiles = {
+                tile_a = 95,
+                pseudo_a = 5
+            }
+        }
+    }
+}
+```
+:::

docs/index.md

@@ -1,2 +1,69 @@
 # About
-Wavewall is a highly-configurable tiling wallpaper generator.
+Wavewall is a tiling wallpaper generator. It takes small images (referred to as tiles) and stitches them together to form a larger, yet still cohesive image.
+
+Wavewall is designed to provide very high control over the output image. You can pick which tiles to use and how often they should appear, and you're even able to recolor every pixel in the output programmatically to fit an existing aesthetic.
+
+***
+
+# How to use Wavewall
+Wavewall is configured using the programming language [lua](https://www.lua.org). If you know it already, great! You'll be excited about the cool stuff this enables wavewall to do. If you don't though, don't worry! Wavewall's configuration is designed to be easy to use even if you've never programmed before. First, check out the [guide](/lua/guide) for the basics, and then get started!
+
+***
+
+# Getting started
+First, create the configuration directory. This is either `$XDG_CONFIG_HOME/wavewall`, or `/home/<user>/.config/wavewall`. Then, inside the directory, create the file `wavewall.lua` and a directory for your tileset, along with a `tileset.lua`. It should be like this afterwards:
+```
+wavewall
+├── my_tileset
+│   └── tileset.lua
+└── wavewall.lua
+```
+
+Now we need to add some tiles. At the moment these are required to be `.png` files, and they all need to be the same size. Running `wavewall template <size>` will create a template `.png` of that size, which you can then draw on to your desire (I found [PIXILART](https://www.pixilart.com) worked pretty well). To speed things up, you can alsy try out one of the tilesets I provide on the [github repo](https://github.com/rohrsben/wavewall/tree/main/tilesets). Put the tiles in your tileset directory like so:
+
+```
+wavewall
+├── my_tileset
+│   ├── tile_a.png
+│   ├── tile_b.png
+│   └── tileset.lua
+└── wavewall.lua
+```
+
+Once you've got some tiles, you just need a configuration. Inside your `.lua` files insert this text:
+::: code-group
+```lua [wavewall.lua]
+local tileset_config = require("my_tileset.tileset")
+
+return {
+    output = {
+        size = {
+            height = 500, -- or, your monitors resolution here!
+            width = 500
+        },
+    },
+
+    tileset = tileset_config
+}
+```
+
+```lua [tileset.lua]
+return {
+    recipes = {
+        first_recipe = { }
+    }
+}
+```
+:::
+
+`first_recipe` has no options, but wavewall will still be able to run. From here, adjust how Wavewall generates your image using the docs!
+***
+
+# The Documentation
+
+The sidebar has a few sections. Here's what they mean:
+- **Configuration**: this section details which options Wavewall allows you to set, how to set them, and what they do
+- **Commands**: Wavewall has a few useful secondary commands, like `wavewall template` from above. This details how to use them and what they do
+- **Lua**: Wavewall adds a few functions to the lua environment to make writing tileset configurations easier. This tells you what's been added and how to use them, as well as a simple lua guide.
+- **UserData**: explains what the functions that are provided return, and how to use them
+- **Other**: some settings require more in-depth explanation. This is their home