docs: too many changes to count

docs/config.toml

@@ -1,7 +1,7 @@
 # hugo server --minify --themesDir ... --baseURL=http://0.0.0.0:1313/theme/hugo-book/
 
 baseURL = 'https://rustybever.be/docs/vieter/'
-title = 'The Rusty Bever - Docs'
+title = 'Vieter - Docs'
 theme = 'hugo-book'
 
 # Book configuration

docs/content/configuration.md

@@ -3,7 +3,7 @@ weight: 20
 ---
 # Configuration
 
-All vieter operations by default try to read in the TOML file `~/.vieterrc` for
+By default, all vieter commands try to read in the TOML file `~/.vieterrc` for
 configuration. The location of this file can be changed by using the `-f` flag.
 
 If the above file doesn't exist or you wish to override some of its settings,
@@ -19,38 +19,78 @@ the value in the environment variable is used.
 {{< hint info >}}
 **Note**  
 All environment variables can also be provided from a file by appending them
-with `_FILE`. This for example allows you to provide the API key from a docker
+with `_FILE`. This for example allows you to provide the API key from a Docker
 secrets file.
 {{< /hint >}}
 
-## Modes
+## Commands
 
-The vieter binary can run in several "modes", indicated by the first argument
-passed to them. Each mode requires a different configuration.
+The first argument passed to Vieter determines which command you wish to use.
+Each of these can contain subcommands (e.g. `vieter repos list`), but all
+subcommands will use the same configuration. Below you can find the
+configuration variable required for each command.
 
-### Server
+### `vieter server`
 
-* `log_level`: defines how much logs to show. Valid values are one of `FATAL`,
-  `ERROR`, `WARN`, `INFO` or `DEBUG`. Defaults to `WARN`
-* `log_file`: log file to write logs to. Defaults to `vieter.log` in the
-  current directory.
+* `log_level`: log verbosity level. Value should be one of `FATAL`, `ERROR`,
+  `WARN`, `INFO` or `DEBUG`.
+    * Default: `WARN`
+* `log_file`: log file to write logs to.
+    * Default: `vieter.log` (in the current directory)
 * `pkg_dir`:  where Vieter should store the actual package archives.
 * `data_dir`: where Vieter stores the repositories, log file & database.
 * `api_key`: the API key to use when authenticating requests.
-* `default_arch`: architecture to always add packages of arch `any` to.
+* `default_arch`: this setting serves two main purposes:
+    * Packages with architecture `any` are always added to this architecture.
+      This prevents the server from being confused when an `any` package is
+      published as the very first package for a repository.
+    * Git repositories added without an `arch` value use this value instead.
 
-### Builder
+
+### `vieter repos`
 
 * `api_key`: the API key to use when authenticating requests.
 * `address`: Base your URL of your Vieter instance, e.g. https://example.com
-* `base_image`: image to use when building a package. It should be an Archlinux
-  image. The default if not configured is `archlinux:base-devel`, but this
-  image only supports arm64. If you require aarch64 support as well, consider
-  using
-  [`menci/archlinuxarm:base-devel`](https://hub.docker.com/r/menci/archlinuxarm)
-  ([GH](https://github.com/Menci/docker-archlinuxarm))
+* `base_image`: image to use when building a package using `vieter repos
+  build`.
+    * Default: `archlinux:base-devel`
 
-### Repos
+### `vieter cron`
+
+* `log_level`: log verbosity level. Value should be one of `FATAL`, `ERROR`,
+  `WARN`, `INFO` or `DEBUG`.
+    * Default: `WARN`
+* `log_file`: log file to write logs to.
+    * Default: `vieter.log` (in `data_dir`)
+* `address`: *public* URL of the Vieter repository server to build for. From
+  this server the list of Git repositories is retrieved. All built packages are
+  published to this server.
+* `api_key`: API key of the above server.
+* `data_dir`: directory to store log file in.
+* `base_image`: Docker image to use when building a package. Any Pacman-based
+  distro image should work, as long as `/etc/pacman.conf` is used &
+  `base-devel` exists in the repositories. Make sure that the image supports
+  the architecture of your cron daemon.
+    * Default: `archlinux:base-devel` (only works on `x86_64`). If you require
+      `aarch64` support, consider using
+      [`menci/archlinuxarm:base-devel`](https://hub.docker.com/r/menci/archlinuxarm)
+      ([GitHub](https://github.com/Menci/docker-archlinuxarm)). This is the image
+      used for the Vieter CI builds.
+* `max_concurrent_builds`: how many builds to run at the same time.
+    * Default: `1`
+* `api_update_frequency`: how frequently (in minutes) to poll the Vieter
+  repository server for a new list of Git repositories to build.
+    * Default: `15`
+* `image_rebuild_frequency`: Vieter periodically builds a builder image using
+  the configured base image. This makes sure build containers do not have to
+  download a lot of packages when updating their system. This setting defines
+  how frequently (in minutes) to rebuild this builder image.
+    * Default: `1440` (every 24 hours)
+* `global_schedule`: build schedule for any Git repository that does not have a
+  schedule defined. 
+    * Default: `0 3` (3AM every night)
+
+### `vieter logs`
 
 * `api_key`: the API key to use when authenticating requests.
 * `address`: Base your URL of your Vieter instance, e.g. https://example.com

docs/content/usage/builds/_index.md

@@ -24,7 +24,7 @@ vieter repos add some-url some-branch some-repository
 ```
 
 Here, `some-url` is the URL of the Git repository containing the PKGBUILD. This
-URL is passed to `git clone`, so the repository should be public. Vieter
+URL is passed to `git clone`, meaning the repository should be public. Vieter
 expects the same format as an AUR Git repository, so you can directly use AUR
 URLs here.
 

docs/content/usage/builds/schedule.md

@@ -0,0 +1,42 @@
+# Cron schedule syntax
+
+The Vieter cron daemon uses a subset of the cron expression syntax to schedule
+builds.
+
+## Format
+
+`a b c d`
+
+* `a`: minutes
+* `b`: hours
+* `c`: days
+* `d`: months
+
+An expression consists of two to four sections. If less than four sections are
+provided, the parser will append `*` until there are four sections. This means
+that `0 3` is the same as `0 3 * *`.
+
+Each section consists of one or more parts, separated by a comma. Each of these
+parts, in turn, can be one of the following (any letters are integers):
+
+* `*`: allow all possible values.
+* `a`: only this value is allowed.
+* `*/n`: allow every n-th value.
+* `a/n`: allow every n-th value, starting at a in the list.
+* `a-b`: allow every value between a and b, bounds included.
+* `a-b/n`: allow every n-th value inside the list of values between a and b,
+  bounds included.
+
+Each section can consist of as many of these parts as necessary.
+
+## Examples
+
+* `0 3`: every day at 03:00AM.
+* `0 0 */7`: every 7th day of the month, at midnight.
+
+## CLI tool
+
+The Vieter binary contains a command that shows you the next matching times for
+a given expression. This can be useful to understand the syntax. For more
+information, see
+[vieter-schedule(1)](https://rustybever.be/man/vieter/vieter-schedule.1.html).

docs/content/usage/repository.md

@@ -20,12 +20,12 @@ Server = https://example.com/$repo/$arch
 SigLevel = Optional
 ```
 
-Here, `$repo` & `$arch` are not variables you have to fill in yourself. Rather,
-Pacman will substitute these when reading the config file. `$repo` is replaced
-by the name between the square brackets (in this case `repo-name`), & `$arch`
-is replaced by your system's architecture, e.g. `x86_64`. Of course, you can
-also fill in these values manually yourself, e.g. if you wish to use a
-different name inside the square brackets.
+Here, `$repo` and `$arch` are not variables you have to fill in yourself.
+Rather, Pacman will substitute these when reading the config file. `$repo` is
+replaced by the name between the square brackets (in this case `repo-name`),
+and `$arch` is replaced by your system's architecture, e.g. `x86_64`. Of
+course, you can also fill in these values manually yourself, e.g. if you wish
+to use a different name inside the square brackets.
 
 Important to note is that, when two repositories contain a package with the
 same name, Pacman will choose the one from the repository that's highest up in