update documentation for backup contract

modules/contracts/backup/docs/default.md

@@ -4,6 +4,11 @@ This NixOS contract represents a backup job
 that will backup one or more files or directories
 at a regular schedule.
 
+It is a contract between a service that has files to be backed up
+and a service that backs up files.
+All options in this contract should be set by the former.
+The latter will then use the values of those options to know what to backup.
+
 ## Contract Reference {#backup-contract-options}
 
 These are all the options that are expected to exist for this contract to be respected.
@@ -16,41 +21,85 @@ source: @OPTIONS_JSON@
 
 ## Usage {#backup-contract-usage}
 
-A service that can be backed up will provide a `backup` option, like for the [Vaultwarden service][vaultwarden-service-backup].
-What this option defines is an implementation detail of that service
-but it will at least define what directories to backup
+A service that can be backed up will provide a `backup` option.
+What this option defines is, from the user perspective - that is _you_ - an implementation detail
+but it will at least define what directories to backup,
+the user to backup with
 and possibly hooks to run before or after the backup job runs.
 
-[vaultwarden-service-backup]: services-vaultwarden.html#services-vaultwarden-options-shb.vaultwarden.backup
+Here is an example module defining such a `backup` option:
 
 ```nix
-shb.<service>.backup
-```
-
-Let's assume a module implementing this contract is available under the `shb.<backup_impl>` variable.
-Then, to actually backup the service, one would write:
-
-```nix
-shb.<backup_impl>.instances."<service>" = shb.<service>.backup // {
-  enable = true;
-
-  # Options specific to backup_impl
+{
+  options = {
+    myservice.backup = lib.mkOption {
+      type = contracts.backup;
+      readOnly = true;
+      default = {
+        user = "myservice";
+        sourceDirectories = [
+          "/var/lib/myservice"
+        ];
+      };
+    };
+  };
 };
 ```
 
-Then, for extra caution, a second backup could be made using another module `shb.<backup_impl_2>`:
+As you can see, NixOS modules are a bit abused to make contracts work.
+Default values are set as well as the `readOnly` attribute to ensure those values stay as defined.
+
+Now, on the other side we have a service that uses this `backup` option and actually backs up files.
+Let's assume such a module is available under the `backupservice` option
+and that one can create multiple backup instances under `backupservice.instances`.
+Then, to actually backup the `myservice` service, one would write:
 
 ```nix
-shb.<backup_impl_2>.instances."<service>" = shb.<service>.backup // {
+backupservice.instances.myservice = myservice.backup // {
   enable = true;
 
-  # Options specific to backup_impl_2
+  repository = {
+    path = "/srv/backup/myservice";
+  };
+
+  # ... Other options specific to backupservice like scheduling.
 };
 ```
 
+It is advised to backup files to different location, to improve redundancy.
+Thanks to using contracts, this can be made easily either with the same `backupservice`:
+
+```nix
+backupservice.instances.myservice_2 = myservice.backup // {
+  enable = true;
+
+  repository = {
+    path = "<remote path>";
+  };
+};
+```
+
+Or with another module `backupservice_2`!
+
 ## Provided Implementations {#backup-contract-impl}
 
+An implementation here is a service that understands the `backup` contract
+and will backup the files accordingly.
+
 One implementation is provided out of the box:
 - [Restic block](blocks-restic.html).
 
 A second one based on `borgbackup` is in progress.
+
+## Services Providing `backup` Option {#backup-contract-services}
+
+- <!-- [ -->Audiobookshelf<!-- ](services-audiobookshelf.html). --> (no manual yet)
+- <!-- [ -->Deluge<!--](services-deluge.html). --> (no manual yet)
+- <!-- [ -->Grocy<!--](services-grocy.html). --> (no manual yet)
+- <!-- [ -->Hledger<!--](services-hledger.html). --> (no manual yet)
+- <!-- [ -->Home Assistant<!--](services-home-assistant.html). --> (no manual yet)
+- <!-- [ -->Jellyfin<!--](services-jellyfin.html). --> (no manual yet)
+- <!-- [ -->LLDAP<!--](blocks-ldap.html). --> (no manual yet)
+- [Nextcloud](services-nextcloud.html#services-nextcloud-server-usage-backup).
+- [Vaultwarden](services-vaultwarden.html#services-vaultwarden-backup).
+- <!-- [ -->*arr<!--](services-arr.html). --> (no manual yet)

modules/services/nextcloud-server/docs/default.md

@@ -275,9 +275,19 @@ shb.nextcloud.postgresSettings = {
 };
 ```
 
-### Backup the Nextcloud data {#services-nextcloud-server-usage-backup}
+### Backup {#services-nextcloud-server-usage-backup}
 
-TODO
+Backing up Nextcloud using the [Restic block](blocks-restic.html) is done like so:
+
+```nix
+shb.restic.instances."nextcloud" = config.shb.nextcloud.backup // {
+  enable = true;
+};
+```
+
+The name `"nextcloud"` in the `instances` can be anything.
+The `config.shb.nextcloud.backup` option provides what directories to backup.
+You can define any number of Restic instances to backup Nextcloud multiple times.
 
 ### Enable Preview Generator App {#services-nextcloud-server-usage-previewgenerator}