starting new job...
branch='trunk'
if ! command -v git >/dev/null 2>&1; then
echo 'byggsteg: git is not on this deployment PATH, so the clone cannot be updated' >&2
exit 1
fi
if ! cd "$dir"; then
echo "byggsteg: cannot enter the clone $dir" >&2
exit 1
fi
root=$(git rev-parse --show-toplevel 2>/dev/null)
if [ "$root" != "$(pwd -P)" ]; then
echo "byggsteg: $dir is not a git checkout; remove it and the next run clones it again" >&2
exit 1
fi
if ! origin=$(git remote get-url origin 2>/dev/null); then
echo "byggsteg: $dir has no origin remote to fetch $branch from" >&2
exit 1
fi
before=$(git rev-parse --short HEAD 2>/dev/null) || before=none
attempt=1
while :; do
if GIT_TERMINAL_PROMPT=0 git fetch --quiet origin "+refs/heads/$branch:refs/remotes/origin/$branch"; then
break
fi
if [ "$attempt" -ge 3 ]; then
echo "byggsteg: could not fetch $branch from $origin after 3 attempts; is the branch still there, and is the remote reachable?" >&2
exit 1
fi
echo "byggsteg: fetching $branch from $origin failed; retrying in $((attempt * 2))s" >&2
sleep $((attempt * 2))
attempt=$((attempt + 1))
done
if ! git checkout --quiet --force -B "$branch" FETCH_HEAD; then
echo "byggsteg: fetched $branch from $origin but could not check it out" >&2
exit 1
fi
after=$(git rev-parse --short HEAD)
if [ "$before" = "$after" ]; then
echo "byggsteg: $branch was already at $after"
else
echo "byggsteg: $branch moved from $before to $after"
fi
byggsteg: trunk moved from 9fe8946 to 3505979Linux wolk-jjba 7.2.11-gnu #1 SMP PREEMPT_DYNAMIC 1 x86_64 GNU/Linux
commit 3505979302fbc2c6b4ec2d66001b1645dc712d36
Author: Josep Bigorra <jjbigorra@gmail.com>
Date: Tue Nov 17 15:44:29 2026 +0100
docs: document every definition in Texinfo
The exceptions, commands, cli and utils modules gain a commentary that says
what their exported names are and mean, the internal helpers get docstrings in
place of comments, and the constants carry a comment. CONTRIBUTING states the
docstring format.
M CONTRIBUTING.md
M src/dokgen/cli.scm
M src/dokgen/commands.scm
M src/dokgen/data.scm
M src/dokgen/exceptions.scm
M src/dokgen/templates/stexi.scm
M src/dokgen/utils.scm-------------------------------------------------------------- Maak 0.14.0: the infinitely extensible command runner Loading tasks from Maak file: /etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm Executing Maak tasks: version-check -------------------------------------------------------------- => Running Maak task: version-check Fail when a file quotes a version other than the one the source states. version 0.6.1 is consistent in 4 files
channels.scm:17:6: warning: channel 'jointhefreeworld' is not trusted
wrote `/tmp/tmp.S8LNUAqXEp'
;;; note: source file ./src/dokgen/data.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/data.scm.go
;;; note: source file ./src/dokgen/exceptions.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/exceptions.scm.go
;;; note: source file ./src/dokgen/utils.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/utils.scm.go
wrote `/tmp/tmp.a3fY3gt0q5'
wrote `/tmp/tmp.BBFQPi83M1'
;;; note: source file ./src/dokgen/commands.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/commands.scm.go
;;; note: source file ./src/dokgen/data.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/data.scm.go
;;; note: source file ./src/dokgen/exceptions.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/exceptions.scm.go
;;; note: source file ./src/dokgen/templates/stexi.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/templates/stexi.scm.go
;;; note: source file ./src/dokgen/utils.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/utils.scm.go
wrote `/tmp/tmp.nai4BDhA36'
;;; note: source file ./src/dokgen/data.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/data.scm.go
;;; note: source file ./src/dokgen/exceptions.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/exceptions.scm.go
;;; note: source file ./src/dokgen/templates/stexi.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/templates/stexi.scm.go
;;; note: source file ./src/dokgen/utils.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/utils.scm.go
wrote `/tmp/tmp.Dpz2soPg2m'
;;; note: source file ./src/dokgen/exceptions.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/exceptions.scm.go
wrote `/tmp/tmp.vhWe85LbzW'
wrote `/tmp/tmp.pQGkayi62f'
wrote `/tmp/tmp.ySi8hiLhia'
wrote `/tmp/tmp.OpMCGX1A9B'
;;; note: source file ./src/dokgen/data.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/data.scm.go
;;; note: source file ./src/dokgen/exceptions.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/exceptions.scm.go
wrote `/tmp/tmp.RDObedJD9u'
wrote `/tmp/tmp.qFn7EnrmF7'
wrote `/tmp/tmp.Lm8PSDKdNq'
wrote `/tmp/tmp.kE2UbeeXk2'
;;; note: source file ./src/dokgen/templates/stexi.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/templates/stexi.scm.go
;;; note: source file ./src/dokgen/data.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/data.scm.go
;;; note: source file ./src/dokgen/exceptions.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/exceptions.scm.go
;;; note: source file ./src/dokgen/utils.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/utils.scm.go
;;; note: source file ./src/dokgen/utils.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/utils.scm.go
wrote `/tmp/tmp.tgM3Dqmh2W'
wrote `/tmp/tmp.eTu6Oap6AC'
WARNING: Use of `load' in declarative module (#{ g111}#). Add #:declarative? #f to your define-module invocation.
--------------------------------------------------------------
Maak 0.14.0: the infinitely extensible command runner
Loading tasks from Maak file: /etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm
Executing Maak tasks: check
--------------------------------------------------------------
=> Running Maak task: check
Compile every source and test module, so a syntax error fails the build.
Each file is compiled on its own, which is what makes one broken file name
itself rather than a pile of them.
Execute command:
guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh -c 'set -eu
find src tests etc -name '\''*.scm'\'' -print0 | xargs -0 -n 1 sh -c '\''guild compile -L ./src -L . -o "$(mktemp)" "$1"'\'' sh'
Executing: guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh -c 'set -eu
find src tests etc -name '\''*.scm'\'' -print0 | xargs -0 -n 1 sh -c '\''guild compile -L ./src -L . -o "$(mktemp)" "$1"'\'' sh'channels.scm:17:6: warning: channel 'jointhefreeworld' is not trusted
;;; note: source file ./src/dokgen/data.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/data.scm.go
;;; note: auto-compilation is enabled, set GUILE_AUTO_COMPILE=0
;;; or pass the --no-auto-compile argument to disable.
;;; compiling ./src/dokgen/data.scm
;;; note: source file ./src/dokgen/exceptions.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/exceptions.scm.go
;;; compiling ./src/dokgen/exceptions.scm
;;; compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/exceptions.scm.go
;;; compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/data.scm.go
*** Entering test group: (dokgen data) ***
*** Entering test group: [procedure] file-path->module-name ***
* PASS: Convert Scheme file path to module name (multi-module library).
* PASS: Convert Scheme file path to module name (single-module library).
*** Leaving test group: [procedure] file-path->module-name ***
*** Entering test group: [procedure] group-api-objects ***
* PASS: A «parameters» group exists when the API exports parameters.
* PASS: All parameters exported by the API are included in their group.
* PASS: All objects in the «parameters» group are actually parameters.
* PASS: Raise &residual-export-exception when unbound export is found.
*** Leaving test group: [procedure] group-api-objects ***
*** Leaving test group: (dokgen data) ***
*** Test suite finished. ***
*** # of expected passes : 6
;;; note: source file ./src/dokgen/templates/stexi.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/templates/stexi.scm.go
;;; note: auto-compilation is enabled, set GUILE_AUTO_COMPILE=0
;;; or pass the --no-auto-compile argument to disable.
;;; compiling ./src/dokgen/templates/stexi.scm
;;; note: source file ./src/dokgen/utils.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/utils.scm.go
;;; compiling ./src/dokgen/utils.scm
;;; compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/utils.scm.go
;;; compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/templates/stexi.scm.go
*** Entering test group: (dokgen templates) ***
*** Entering test group: [procedure] api-binding ***
* PASS: Render a binding that holds a record type.
* PASS: Render a binding that holds a record.
* PASS: Render a parameterless procedure.
* PASS: Render a procedure containing @verbatim examples.
* PASS: Render undocumented procedure.
* PASS: Render a documented macro.
* PASS: Render an undocumented macro.
* PASS: Render a parameter.
*** Leaving test group: [procedure] api-binding ***
*** Entering test group: [procedure] module-description ***
* PASS: Render standard module commentary.
* PASS: Render block-commented module commentary.
*** Leaving test group: [procedure] module-description ***
*** Entering test group: [procedure] procedure-parameters ***
* PASS: Render empty parameters.
* XPASS: Render required parameters.
source-file: tests/test-templates-stexi.scm
source-line: 269
source-form: (test-equal
"Render required parameters."
"param1 param2 param3"
(stexi:procedure-parameters required-params))
expected-value: param1 param2 param3
expected-error: #f
actual-value: param1 param2 param3
actual-error: #f
* XPASS: Render optional parameters.
source-file: tests/test-templates-stexi.scm
source-line: 280
source-form: (test-equal
"Render optional parameters."
"OPT: opt1 opt2"
(stexi:procedure-parameters optional-params))
expected-value: OPT: opt1 opt2
expected-error: #f
actual-value: OPT: opt1 opt2
actual-error: #f
* PASS: Render keyword parameters.
* PASS: Render note when arbitrary keyword parameters are allowed.
* PASS: Render args parameter.
*** Leaving test group: [procedure] procedure-parameters ***
*** Leaving test group: (dokgen templates) ***
*** Test suite finished. ***
*** # of expected passes : 14
*** # of unexpected passes : 2
*** Entering test group: (dokgen utils) ***
*** Entering test group: [procedure] min-indent ***
* PASS: Find the shorter number of spaces used for indentation.
* PASS: The indentation of an empty string is zero.
* PASS: The indentation of a single-line string is zero.
*** Leaving test group: [procedure] min-indent ***
*** Entering test group: [procedure] tabs->spaces ***
* PASS: Replace tabs with default number of spaces.
* PASS: Replace tabs with custom number of spaces.
*** Leaving test group: [procedure] tabs->spaces ***
*** Entering test group: [procedure] trim ***
* PASS: Trim off N spaces.
* PASS: Trim off more than N spaces.
*** Leaving test group: [procedure] trim ***
*** Entering test group: [procedure] unindent ***
* PASS: Remove unwanted tab indentation.
* PASS: Remove unwanted space indentation.
* PASS: Leave desired tab indentation.
* PASS: Handle empty docstring.
* PASS: Handle one-line docstring.
*** Leaving test group: [procedure] unindent ***
*** Leaving test group: (dokgen utils) ***
*** Test suite finished. ***
*** # of expected passes : 12
--------------------------------------------------------------
Maak 0.14.0: the infinitely extensible command runner
Loading tasks from Maak file: /etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm
Executing Maak tasks: test
--------------------------------------------------------------
=> Running Maak task: test
Run every test file under tests/.
SRFI-64 never turns a failure into an exit status, so each file goes through
`etc/run-test.scm', which does. The `test-module-*' files are fixtures the
suites document, not suites.
Execute command:
guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh -c 'set -eu
status=0
for file in tests/test-*.scm; do
case $file in tests/test-module-*) continue ;; esac
guile -L ./src -L . etc/run-test.scm "$file" || status=1
done
rm -f ./*.log
exit $status'
Executing: guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh -c 'set -eu
status=0
for file in tests/test-*.scm; do
case $file in tests/test-module-*) continue ;; esac
guile -L ./src -L . etc/run-test.scm "$file" || status=1
done
rm -f ./*.log
exit $status'channels.scm:17:6: warning: channel 'jointhefreeworld' is not trusted
API documentation saved to manual/api
;;; note: source file /etc/byggsteg/job-clone/guile-dokgen/trunk/bin/../src/dokgen/cli.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/cli.scm.go
;;; note: auto-compilation is enabled, set GUILE_AUTO_COMPILE=0
;;; or pass the --no-auto-compile argument to disable.
;;; compiling /etc/byggsteg/job-clone/guile-dokgen/trunk/bin/../src/dokgen/cli.scm
;;; note: source file /etc/byggsteg/job-clone/guile-dokgen/trunk/bin/../src/dokgen/commands.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/commands.scm.go
;;; compiling /etc/byggsteg/job-clone/guile-dokgen/trunk/bin/../src/dokgen/commands.scm
;;; compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/commands.scm.go
;;; compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/cli.scm.go
--------------------------------------------------------------
Maak 0.14.0: the infinitely extensible command runner
Loading tasks from Maak file: /etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm
Executing Maak tasks: docs-check
--------------------------------------------------------------
=> Running Maak task: docs-check
Fail when manual/api/index.texi is not what the sources generate.
The reference is generated, so a committed copy that differs from a fresh one
is a procedure that was changed without the documentation following.
Execute command:
guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh bin/dokgen api --destination manual/api ./src/dokgen
Executing: guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh bin/dokgen api --destination manual/api ./src/dokgen
diff --git a/manual/api/index.texi b/manual/api/index.texi
index cee0e5e..92cb1dd 100644
--- a/manual/api/index.texi
+++ b/manual/api/index.texi
@@ -17,6 +17,13 @@ The following is the list of modules provided by this library.
This module defines the command-line interface of the @command{dokgen}
program. See the @ref{CLI} section for additional information.
+The variable @code{spec} is the specification of the interface, a
+@code{<configuration>} record as defined by the guile-config library. It
+names the program, states its version, license and author, and declares
+the @code{api} subcommand with its @code{sources} argument and its
+@code{destination} keyword. The procedure @code{call} dispatches a
+command line to the procedure that carries it out.
+
@c %end of fragment
@@ -98,6 +105,11 @@ provided by the command-line interface of the @command{dokgen} program.
See the @ref{CLI} and @xref{dokgen_cli,(dokgen cli)} sections for
additional information.
+The variable @code{DEFAULT_DOC_PATH} is the directory where the API
+documentation is saved when the user does not choose one; its value is
+@samp{doc/api}. The documentation is written to a file named
+@file{index.texi} inside that directory.
+
@c %end of fragment
@@ -281,6 +293,37 @@ If the FIELD does not exist, a @var{no-such-field} exception is raised.
@c %start of fragment
+This module defines the exceptions raised by the @command{dokgen}
+program.
+
+The exception type @code{&residual-export-exception} is raised when a
+module exports a name that is not bound to any object. This can occur,
+for example, when a developer removes a procedure, variable, etc., from
+a module but forgets to remove its name from the export list. It
+provides the following procedures:
+
+@itemize @bullet
+@item
+@code{make-residual-export-exception}: the constructor. It takes the
+reason, the exported residue and the exporter module, in that order.
+
+@item
+@code{residual-export-exception?}: the predicate.
+
+@item
+@code{residual-export-exception-reason}: a string that explains the
+problem.
+
+@item
+@code{residual-export-exception-exported-residue}: the symbol that was
+exported but is unbound.
+
+@item
+@code{residual-export-exception-exporter-module}: the name of the module
+that exports the residue, as a list of symbols.
+
+@end itemize
+
@c %end of fragment
@@ -478,7 +521,10 @@ Default values for optional and keyword parameters are not included.
@c %start of fragment
This module defines helper procedures that didn't quite fit anywhere
-else.
+else. They normalize the indentation of documentation strings before
+they are rendered. The constant @code{DEFAULT_SPACE_INDENT_SIZE} is the
+number of spaces that replace a tab when no other size is given; its
+value is 2.
@c %end of fragment
maak: error: command failed (exit code 1): git -C . diff --exit-code -- manual/api
hint: Fix the command above, or run `maak --dry-run' to inspect it first.channels.scm:17:6: warning: channel 'jointhefreeworld' is not trustedWARNING: Use of `load' in declarative module (#{ g111}#). Add #:declarative? #f to your define-module invocation.channels.scm:17:6: warning: channel 'jointhefreeworld' is not trustedchannels.scm:17:6: warning: channel 'jointhefreeworld' is not trusted(lambda()
`((task . ("maak-version-check" "maak-check" "maak-test" "maak-docs-check" "maak-manual"))
(project . "guile-dokgen")
(branch-name . "trunk")
(clone-url . "https://github.com/jjba23/guile-dokgen.git")))