~ruther/guix-local

766ad072ad90d4ffc161cb83e29910b7bb3a9d54 — Herman Rimm 1 year, 9 months ago 41b5b72
services: configuration: Document multiple configurations per field.

* gnu/services/configuration.scm (generate-documentation): Filter for all
configurations associated with each field-name.
* doc/guix.texi (Complex Configurations): Describe use case for multiple
field-names.

Change-Id: I6d1e7b8858231aa05fda884b31a9bd0a48f07293
Signed-off-by: Ludovic Courtès <ludo@gnu.org>
2 files changed, 10 insertions(+), 3 deletions(-)

M doc/guix.texi
M gnu/services/configuration.scm
M doc/guix.texi => doc/guix.texi +3 -1
@@ 44702,7 44702,9 @@ available for the configuration record.
@var{sub-documentation} is a @code{(@var{field-name}
@var{configuration-name})} tuple.  @var{field-name} is the name of the
field which takes another configuration record as its value, and
@var{configuration-name} is the name of that configuration record.
@var{configuration-name} is the name of that configuration record.  The
same value may be used for multiple @var{field-name}s, in case a field
accepts different types of configurations.

@var{sub-documentation} is only needed if there are nested configuration
records.  For example, the @code{getmail-configuration} record

M gnu/services/configuration.scm => gnu/services/configuration.scm +7 -2
@@ 7,6 7,7 @@
;;; Copyright © 2021 Andrew Tropin <andrew@trop.in>
;;; Copyright © 2022 Maxime Devos <maximedevos@telenet.be>
;;; Copyright © 2023 Bruno Victal <mirai@makinata.eu>
;;; Copyright © 2024 Herman Rimm <herman@rimm.ee>
;;;
;;; This file is part of GNU Guix.
;;;


@@ 460,8 461,12 @@ DEFAULT."
                           (para ,@field-docs)
                           ,@(append-map
                              generate
                              (or (assq-ref sub-documentation field-name)
                                  '())))))
                              (filter-map
                                (match-lambda
                                  ((name config)
                                   (and (eq? name field-name)
                                        config)))
                                sub-documentation)))))
               fields)))))))
  (stexi->texi `(*fragment* . ,(generate documentation-name))))