Message ID | 07aed2e6ffe6c6fdab4a38207cafb7d3169c6e11.1623243063.git.public@yoctocell.xyz |
---|---|
State | Accepted |
Headers | show |
Series | Some improvements to (gnu services configuration) | expand |
Context | Check | Description |
---|---|---|
cbaines/comparison | success | View comparision |
cbaines/git branch | success | View Git branch |
cbaines/applying patch | success | View Laminar job |
cbaines/issue | success | View issue |
Hello Xinglu! Xinglu Chen <public@yoctocell.xyz> writes: > * gnu/services/configuration (generate-documentation): Make the formatting of > the generated docs more consistent with the rest of the docs in the “Services” > section of the manual. I've modified the commit message to be more in line with the GNU change log style (see 'info (standards) Style of Change Logs'), like so: services: configuration: Uniformize the generated documentation. 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. > --- > gnu/services/configuration.scm | 54 ++++++++++++++++++---------------- > 1 file changed, 28 insertions(+), 26 deletions(-) > > diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm > index f23840ee6d..abcbc70520 100644 > --- a/gnu/services/configuration.scm > +++ b/gnu/services/configuration.scm > @@ -239,32 +239,34 @@ 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) I've used this opportunity to re-indent the code a bit, so that it'd fit under 80 characters column width. Thanks for this neat improvement! Maxim
diff --git a/gnu/services/configuration.scm b/gnu/services/configuration.scm index f23840ee6d..abcbc70520 100644 --- a/gnu/services/configuration.scm +++ b/gnu/services/configuration.scm @@ -239,32 +239,34 @@ 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)