docs: option docs improvements

- add missing description and defaultText fields
- add dmarcReporting option group
- render examples

default.nix

@@ -662,8 +662,11 @@ in
       email = mkOption {
         type = types.str;
         default = with cfg.dmarcReporting; "${localpart}@${domain}";
-        example = "dmarc-noreply@example.com";
+        defaultText = literalExpression ''"''${localpart}@''${domain}"'';
         readOnly = true;
+        description = ''
+          The email address used for outgoing DMARC reports. Read-only.
+        '';
       };
 
       organizationName = mkOption {
@@ -678,6 +681,7 @@ in
       fromName = mkOption {
         type = types.str;
         default = cfg.dmarcReporting.organizationName;
+        defaultText = literalExpression "organizationName";
         description = ''
           The sender name for DMARC reports. Defaults to the organization name.
         '';

scripts/generate-rst-options.py

@@ -1,6 +1,7 @@
 import json
 import sys
 import re
+import textwrap
 
 header = """
 Mailserver Options
@@ -19,6 +20,7 @@ template = """
 
 {type}
 {default}
+{example}
 """
 
 f = open(sys.argv[1])
@@ -30,36 +32,44 @@ options = {k: v for k, v in options.items()
 groups = ["mailserver.loginAccount",
           "mailserver.certificate",
           "mailserver.dkim",
+          "mailserver.dmarcReporting",
           "mailserver.fullTextSearch",
           "mailserver.redis",
           "mailserver.monitoring",
           "mailserver.backup",
           "mailserver.borg"]
 
+def render_option_value(opt, attr):
+  if attr in opt:
+      if isinstance(opt[attr], dict) and '_type' in opt[attr]:
+          if opt[attr]['_type'] == 'literalExpression':
+              if '\n' in opt[attr]['text']:
+                  res = '\n.. code:: nix\n\n' + textwrap.indent(opt[attr]['text'], '  ') + '\n'
+              else:
+                  res = '``{}``'.format(opt[attr]['text'])
+          elif opt[attr]['_type'] == 'literalDocBook':
+              res = opt[attr]['text']
+      else:
+          s = str(opt[attr])
+          if s == "":
+              res = '``""``'
+          elif '\n' in s:
+              res = '\n.. code::\n\n' + textwrap.indent(s, '  ') + '\n'
+          else:
+              res = '``{}``'.format(s)
+      res = '- ' + attr + ': ' + res
+  else:
+      res = ""
+  return res
 
 def print_option(name, value):
-    if 'default' in value:
-        if value['default'] == "":
-            default = '``""``'
-        elif isinstance(value['default'], dict) and '_type' in value['default']:
-            if value['default']['_type'] == 'literalExpression':
-                default = '``{}``'.format(value['default']['text'])
-            if value['default']['_type'] == 'literalDocBook':
-                default = value['default']['text']
-        else:
-            default = '``{}``'.format(value['default'])
-        # Some default values contains OUTPUTPATHS which make the
-        # output not stable across nixpkgs updates.
-        default = re.sub('/nix/store/[\w.-]*/', '<OUTPUT-PATH>/', default)  # noqa
-        default = '- Default: ' + default
-    else:
-        default = ""
     print(template.format(
         key=name,
         line="-"*len(name),
-        description=value['description'],
+        description=value['description'] or "",
-        type="- Type: ``{}``".format(value['type']),
+        type="- type: ``{}``".format(value['type']),
-        default=default))
+        default=render_option_value(value, 'default'),
+        example=render_option_value(value, 'example')))
 
 
 print(header)