[PATCH pmg-docs] gen-pmg.conf.5: check key to section mapping only in docs build

[PATCH pmg-docs] gen-pmg.conf.5: check key to section mapping only in docs build

[Stoiko Ivanov]

adding a new option to pmg.conf currently requires updating pmg-docs,
as both are tightly coupled through gen-pmg.conf.pl.

The checks in gen-pmg.conf.pl ensure that most keys (some are
explicitly ignored) are put in a category to be rendered in the fitting
section of the docs.

While ensuring our docs are consistent makes sense, the mutual
dependency of pmg-api and pmg-docs slows down things like `sbuild`, or
rolling out fixes for older releases - as it requires an update of
pmg-docs-generator before upgrading pmg-api.

The patch reverses the logic of:
 f475c3f ("gen-pmg.conf.5: allow to overwrite undocumented key error for bootstrapping")
by not dying in the default case. Ensuring that each config key is in
a category happens when building pmg-docs - by setting the
PMG_DOCS_IGNORE_MISSING_KEY explicitly to 0 in the Makefile.

tested by removing an existing key from gen-pmg.conf.5-opts.pl, and
building pmg-api, followed by building pmg-docs, which failed.
the pmg.conf(5) manpage still had the key present.

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
---
 Makefile               | 2 ++
 gen-pmg.conf.5-opts.pl | 4 +++-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 52980a6..6031ef6 100644
--- a/Makefile
+++ b/Makefile
@@ -15,6 +15,8 @@ DOC_DEB=$(DOC_PACKAGE)_$(DEB_VERSION_UPSTREAM_REVISION)_all.deb
 export SOURCE_DATE_EPOCH ?= $(shell dpkg-parsechangelog -STimestamp)
 SOURCE_DATE_HUMAN := $(shell date -d "@$(SOURCE_DATE_EPOCH)")
 
+# ensure all pmg.conf keys are accounted for in their respective section.
+export PMG_DOCS_IGNORE_MISSING_KEY ?= 0
 
 all: index.html
 
diff --git a/gen-pmg.conf.5-opts.pl b/gen-pmg.conf.5-opts.pl
index 3ef9d98..2684719 100755
--- a/gen-pmg.conf.5-opts.pl
+++ b/gen-pmg.conf.5-opts.pl
@@ -75,6 +75,8 @@ my $key_groups = {
 	}],
 };
 
+my $die_on_missing = !( $ENV{PMG_DOCS_IGNORE_MISSING_KEY} // 1);
+
 if (1) {
     # verify if we document all mail settings
     my $plugin = PMG::Config::Base->lookup('mail');
@@ -98,7 +100,7 @@ if (1) {
 	next if $k =~ m/^max_(filters|policy|smtpd_in|smtpd_out)$/;
 
 	if (!defined($found_mail_keys->{$k})) {
-	    die "undocumented key '$k'" if !$ENV{PMG_DOCS_IGNORE_MISSING_KEY};
+	    die "undocumented key '$k'" if $die_on_missing;
 	    warn "WARNING: undocumented key '$k'\n";
 	}
     }
-- 
2.47.3