From 208021ee1c145aeaf8735c4e91134575a4145665 Mon Sep 17 00:00:00 2001 From: DavHau Date: Thu, 4 Jul 2024 13:32:57 +0700 Subject: [PATCH] reference docs: add missing `description fields` and enforce it from now on --- clanModules/postgresql/default.nix | 4 +++ clanModules/syncthing/default.nix | 4 +++ docs/nix/get-module-docs.nix | 2 +- nixosModules/clanCore/facts/default.nix | 35 ++++++++++++++++--------- nixosModules/clanCore/state.nix | 3 +++ nixosModules/clanCore/vars/settings.nix | 3 +++ 6 files changed, 37 insertions(+), 14 deletions(-) diff --git a/clanModules/postgresql/default.nix b/clanModules/postgresql/default.nix index d24645eb..d23565ad 100644 --- a/clanModules/postgresql/default.nix +++ b/clanModules/postgresql/default.nix @@ -91,6 +91,7 @@ in options.clan.postgresql = { # we are reimplemeting ensureDatabase and ensureUser options here to allow to create databases with options databases = lib.mkOption { + description = "Databases to create"; default = { }; type = lib.types.attrsOf ( lib.types.submodule ( @@ -114,6 +115,7 @@ in description = "Create the database if it does not exist."; }; create.options = lib.mkOption { + description = "Options to pass to the CREATE DATABASE command."; type = lib.types.lazyAttrsOf lib.types.str; default = { }; example = { @@ -135,12 +137,14 @@ in ); }; users = lib.mkOption { + description = "Users to create"; default = { }; type = lib.types.attrsOf ( lib.types.submodule ( { name, ... }: { options.name = lib.mkOption { + description = "User name"; type = lib.types.str; default = name; }; diff --git a/clanModules/syncthing/default.nix b/clanModules/syncthing/default.nix index 1bf2cb7d..e32ea20a 100644 --- a/clanModules/syncthing/default.nix +++ b/clanModules/syncthing/default.nix @@ -7,6 +7,10 @@ { options.clan.syncthing = { id = lib.mkOption { + description = '' + The ID of the machine. + It is generated automatically by default. + ''; type = lib.types.nullOr lib.types.str; example = "BABNJY4-G2ICDLF-QQEG7DD-N3OBNGF-BCCOFK6-MV3K7QJ-2WUZHXS-7DTW4AS"; default = config.clan.core.facts.services.syncthing.public."syncthing.pub".value or null; diff --git a/docs/nix/get-module-docs.nix b/docs/nix/get-module-docs.nix index 97c4225f..84072137 100644 --- a/docs/nix/get-module-docs.nix +++ b/docs/nix/get-module-docs.nix @@ -30,7 +30,7 @@ let options: pkgs.nixosOptionsDoc { options = options; - warningsAreErrors = false; + warningsAreErrors = true; }; # clanModules docs diff --git a/nixosModules/clanCore/facts/default.nix b/nixosModules/clanCore/facts/default.nix index 4fd84a88..f1121e2d 100644 --- a/nixosModules/clanCore/facts/default.nix +++ b/nixosModules/clanCore/facts/default.nix @@ -67,9 +67,19 @@ publicDirectory = lib.mkOption { type = lib.types.nullOr lib.types.path; default = null; + description = '' + The directory where public facts are stored. + ''; }; services = lib.mkOption { + description = '' + Services to generate secrets and facts for. + Each service can have a generator script which generates the secrets and facts. + The generator script is expected to generate all secrets and facts defined for this service. + + A `service` does not need to ba analogous to a systemd service, it can be any group of facts and secrets that need to be generated together. + ''; default = { }; type = lib.types.attrsOf ( lib.types.submodule (service: { @@ -82,6 +92,9 @@ ''; }; generator = lib.mkOption { + description = '' + The generator to generate the secrets and facts for this service. + ''; type = lib.types.submodule ( { config, ... }: { @@ -151,6 +164,9 @@ ); }; secret = lib.mkOption { + description = '' + Secret facts to generate for this service. + ''; default = { }; type = lib.types.attrsOf ( lib.types.submodule (secret: { @@ -182,11 +198,11 @@ }; }) ); - description = '' - path where the secret is located in the filesystem - ''; }; public = lib.mkOption { + description = '' + Public facts to generate for this service. + ''; default = { }; type = lib.types.attrsOf ( lib.types.submodule (fact: { @@ -208,6 +224,9 @@ config.clan.core.clanDir + "/machines/${config.clan.core.machineName}/facts/${fact.config.name}"; }; value = lib.mkOption { + description = '' + The value of the public fact. + ''; defaultText = lib.literalExpression "\${config.clan.core.clanDir}/\${fact.config.path}"; type = lib.types.nullOr lib.types.str; default = @@ -231,15 +250,5 @@ ./public/in_repo.nix ./public/vm.nix - - # (lib.mkRenamedOptionModule - # [ - # "clanCore" - # ] - # [ - # "clan" - # "core" - # ] - # ) ]; } diff --git a/nixosModules/clanCore/state.nix b/nixosModules/clanCore/state.nix index 5298ccd9..17757fed 100644 --- a/nixosModules/clanCore/state.nix +++ b/nixosModules/clanCore/state.nix @@ -7,6 +7,9 @@ { # interface options.clan.core.state = lib.mkOption { + description = '' + Define state directories to backup and restore + ''; default = { }; type = lib.types.attrsOf ( lib.types.submodule ( diff --git a/nixosModules/clanCore/vars/settings.nix b/nixosModules/clanCore/vars/settings.nix index dbab1e92..dd3e8f7c 100644 --- a/nixosModules/clanCore/vars/settings.nix +++ b/nixosModules/clanCore/vars/settings.nix @@ -64,6 +64,9 @@ publicDirectory = lib.mkOption { type = lib.types.nullOr lib.types.path; default = null; + description = '' + The directory where public facts are stored. + ''; }; }; }