From ad945029a2dbd1fb741be573f13e42c061e72d0f Mon Sep 17 00:00:00 2001 From: Xinglu Chen Date: Wed, 9 Jun 2021 15:06:26 +0200 Subject: services: configuration: Uniformize the generated documentation. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make the formatting of the generated docs more consistent with the rest of the docs in the “Services” section of the manual. * gnu/services/configuration (generate-documentation): Represent the data type documentation of a field using a DEFTP table rather than DEFTYPEVR elements. Modified-by: Maxim Cournoyer Signed-off-by: Maxim Cournoyer --- gnu/services/configuration.scm | 57 +++++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 26 deletions(-) (limited to 'gnu/services/configuration.scm') diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm index fd07b6fa49..3974fba92d 100644 --- a/gnu/services/configuration.scm +++ b/gnu/services/configuration.scm @@ -255,32 +255,37 @@ does not have a default value" field kind))) (define (generate configuration-name) (match (assq-ref documentation configuration-name) ((fields . sub-documentation) - `((para "Available " (code ,(str configuration-name)) " fields are:") - ,@(map - (lambda (f) - (let ((field-name (configuration-field-name f)) - (field-type (configuration-field-type f)) - (field-docs (cdr (texi-fragment->stexi - (configuration-field-documentation f)))) - (default (catch #t - (configuration-field-default-value-thunk f) - (lambda _ '%invalid)))) - (define (show-default? val) - (or (string? val) (number? val) (boolean? val) - (and (symbol? val) (not (eq? val '%invalid))) - (and (list? val) (and-map show-default? val)))) - `(deftypevr (% (category - (code ,(str configuration-name)) " parameter") - (data-type ,(str field-type)) - (name ,(str field-name))) - ,@field-docs - ,@(if (show-default? default) - `((para "Defaults to " (samp ,(str default)) ".")) - '()) - ,@(append-map - generate - (or (assq-ref sub-documentation field-name) '()))))) - fields))))) + `((deftp (% (category "Data Type") (name ,(str configuration-name))) + (para "Available " (code ,(str configuration-name)) " fields are:") + (table + (% (formatter (asis))) + ,@(map + (lambda (f) + (let ((field-name (configuration-field-name f)) + (field-type (configuration-field-type f)) + (field-docs (cdr (texi-fragment->stexi + (configuration-field-documentation f)))) + (default (catch #t + (configuration-field-default-value-thunk f) + (lambda _ '%invalid)))) + (define (show-default? val) + (or (string? val) (number? val) (boolean? val) + (and (symbol? val) (not (eq? val '%invalid))) + (and (list? val) (and-map show-default? val)))) + + `(entry (% (heading + (code ,(str field-name)) + ,@(if (show-default? default) + `(" (default: " + (code ,(str default)) ")") + '()) + " (type: " ,(str field-type) ")")) + (para ,@field-docs) + ,@(append-map + generate + (or (assq-ref sub-documentation field-name) + '()))))) + fields))))))) (stexi->texi `(*fragment* . ,(generate documentation-name)))) (define (configuration->documentation configuration-symbol) -- cgit 1.4.1 From 8e1f94421873777c6bb0b83daa4f81cbacc8b3ff Mon Sep 17 00:00:00 2001 From: Xinglu Chen Date: Wed, 9 Jun 2021 15:06:27 +0200 Subject: services: configuration: Derive the default value from the package variable. If the type of a configuration field is a package, show the name of its package *variable* as the default value. * gnu/services/configuration.scm (generate-documentation){show-default} {package->symbol}: New nested procedures. Use them to format the field entries. Co-authored-by: Maxim Cournoyer Signed-off-by: Maxim Cournoyer --- gnu/services/configuration.scm | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) (limited to 'gnu/services/configuration.scm') diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm index 3974fba92d..df3d3b6f9b 100644 --- a/gnu/services/configuration.scm +++ b/gnu/services/configuration.scm @@ -25,10 +25,12 @@ #:use-module (guix records) #:use-module (guix gexp) #:use-module ((guix utils) #:select (source-properties->location)) + #:use-module ((guix diagnostics) #:select (location-file)) + #:use-module ((guix modules) #:select (file-name->module-name)) #:autoload (texinfo) (texi-fragment->stexi) #:autoload (texinfo serialize) (stexi->texi) #:use-module (ice-9 match) - #:use-module ((srfi srfi-1) #:select (append-map)) + #:use-module (srfi srfi-1) #:use-module (srfi srfi-34) #:use-module (srfi srfi-35) #:export (configuration-field @@ -252,6 +254,21 @@ does not have a default value" field kind))) ;; A little helper to make it easier to document all those fields. (define (generate-documentation documentation documentation-name) (define (str x) (object->string x)) + + (define (package->symbol package) + "Return the first symbol name of a package that matches PACKAGE, else #f." + (let* ((module (file-name->module-name + (location-file (package-location package)))) + (symbols (filter-map + identity + (module-map (lambda (symbol var) + (and (equal? package (variable-ref var)) + symbol)) + (resolve-module module))))) + (if (null? symbols) + #f + (first symbols)))) + (define (generate configuration-name) (match (assq-ref documentation configuration-name) ((fields . sub-documentation) @@ -270,14 +287,21 @@ does not have a default value" field kind))) (lambda _ '%invalid)))) (define (show-default? val) (or (string? val) (number? val) (boolean? val) + (package? val) (and (symbol? val) (not (eq? val '%invalid))) (and (list? val) (and-map show-default? val)))) + (define (show-default val) + (cond + ((package? val) + (symbol->string (package->symbol val))) + (else (str val)))) + `(entry (% (heading (code ,(str field-name)) ,@(if (show-default? default) `(" (default: " - (code ,(str default)) ")") + (code ,(show-default default)) ")") '()) " (type: " ,(str field-type) ")")) (para ,@field-docs) -- cgit 1.4.1