diff options
| -rw-r--r-- | Makefile.am | 8 | ||||
| -rw-r--r-- | doc/drmaa.texi | 7 | ||||
| -rw-r--r-- | doc/snarf.scm | 104 |
3 files changed, 118 insertions, 1 deletions
diff --git a/Makefile.am b/Makefile.am index ee467f0..9696eda 100644 --- a/Makefile.am +++ b/Makefile.am @@ -24,7 +24,7 @@ nobase_go_DATA = $(GOBJECTS) guile_install_go_files = install-nobase_goDATA $(guile_install_go_files): install-nobase_modDATA -EXTRA_DIST = $(SOURCES) $(NOCOMP_SOURCES) drmaa/v1/ffi.ffi +EXTRA_DIST = $(SOURCES) $(NOCOMP_SOURCES) drmaa/v1/ffi.ffi doc/snarf.scm GUILE_WARNINGS = -Wunbound-variable -Warity-mismatch -Wformat SUFFIXES = .scm .go .ffi .scm.go: @@ -56,7 +56,12 @@ AM_SCM_LOG_FLAGS = --no-auto-compile -L "$(top_srcdir)" AM_TESTS_ENVIRONMENT = abs_top_srcdir="$(abs_top_srcdir)" + +doc/low.texi: drmaa/v1/low.go + $(AM_V_GEN)$(top_builddir)/pre-inst-env $(GUILE) doc/snarf.scm + info_TEXINFOS = doc/drmaa.texi +drmaa_TEXINFOS = doc/low.texi dvi: # Don't build dvi docs EXTRA_DIST += README.org \ @@ -92,6 +97,7 @@ clean-go: .NOTPARALLEL: CLEANFILES = \ + doc/low.texi \ drmaa/v1/ffi.scm \ $(GOBJECTS) \ $(TESTS:tests/%.scm=%.log) diff --git a/doc/drmaa.texi b/doc/drmaa.texi index 494adc1..1146725 100644 --- a/doc/drmaa.texi +++ b/doc/drmaa.texi @@ -49,6 +49,7 @@ This document describes Guile DRMAA version @value{VERSION}. @menu * Introduction:: Why Guile DRMAA? * Installation:: How do I install it? +* Low-level bindings:: Bindings that closely wrap the library procedures. @end menu @c ********************************************************************* @@ -84,4 +85,10 @@ If you want to build the sources from the source repository you need to bootstrap the build system first. Run the @code{bootstrap.sh} script first and then perform the above steps. +@c ********************************************************************* +@node Low-level bindings +@chapter Low-level bindings + +@include low.texi + @bye diff --git a/doc/snarf.scm b/doc/snarf.scm new file mode 100644 index 0000000..5dd2f7d --- /dev/null +++ b/doc/snarf.scm @@ -0,0 +1,104 @@ +;;; Copyright © 2021 Ricardo Wurmus <rekado@elephly.net> +;;; +;;; This program is free software; you can redistribute it and/or modify it +;;; under the terms of the GNU General Public License as published by +;;; the Free Software Foundation; either version 3 of the License, or (at +;;; your option) any later version. +;;; +;;; This program is distributed in the hope that it will be useful, but +;;; WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;; GNU General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with this program. If not, see <http://www.gnu.org/licenses/>. + +;;;; Commentary: +;;; +;;; This script extracts docstrings from a module and spits out a +;;; TexInfo file. +;;; +;;;; Code: + +(use-modules (ice-9 match) + (ice-9 session)) + +(define (arguments->string proc) + (match (procedure-arguments proc) + ((('required . req-names) + ('optional . opt-names) + ('keyword . kw-names) + ('allow-other-keys? . any) + ('rest . rest)) + (string-join + (list + (format #false "~{@var{~a}~^ ~}" req-names) + (format #false "~:[[~{@var{~a}~^ ~}]~;~]" (null? opt-names) opt-names) + (format #false "~:[[~{@var{~a}~^ ~}]~;~]" (null? kw-names) (map car kw-names)) + (format #false "~@[@var{~a} ...~]" rest)))))) + +(define (fancy-docstring proc known-procedures) + (define arguments + (match (procedure-arguments proc) + ((('required . req-names) + ('optional . opt-names) + ('keyword . kw-names) + ('allow-other-keys? . any) + ('rest . rest)) + (let ((kws (map (compose keyword->symbol car) + kw-names))) + (map symbol->string + (append req-names opt-names kws + (if rest (list rest) '()))))))) + (define (argument? word) + (member (string-downcase word) arguments)) + (define* (maybe-wrap word #:optional (trail "")) + (let ((word* (string-drop-right word (string-length trail)))) + (if (or (member word* '("#TRUE" "#FALSE" "*")) + (member word* known-procedures) + (argument? word*)) + (string-append "@var{" (string-downcase word*) "}" trail) + (string-append word* trail)))) + (let ((words (string-tokenize (procedure-documentation proc)))) + (string-join (map (lambda (word) + (cond + ((string-suffix? "." word) + (maybe-wrap word ".")) + ((string-suffix? "," word) + (maybe-wrap word ",")) + ((string-suffix? ";" word) + (maybe-wrap word ";")) + (else + (maybe-wrap word)))) + words)))) + +(define (docs module) + (define known-procedures + (module-map (lambda (sym var) + (string-upcase (symbol->string sym))) + (resolve-interface module))) + (let ((unsorted + (module-map + (lambda (sym var) + (let ((proc (variable-ref var))) + (cons sym (format #false + "\ +@cindex ~a +@deffn {Scheme Procedure} ~a ~a +~a +@end deffn +" sym sym + (arguments->string proc) + (fancy-docstring proc known-procedures))))) + (resolve-interface module)))) + (sort unsorted (lambda (a b) + (string< (symbol->string (car a)) + (symbol->string (car b))))))) + +(with-output-to-file "doc/low.texi" + (lambda () + (for-each (match-lambda + ((sym . doc) + (display doc) + (newline))) + (docs '(drmaa v1 low))))) |