Re: Compile skribilo doc containing guix channel references

[Phil <phil@beadling.co.uk>]

Hi,

Ludovic Courtès writes:

> We toyed with Skribilo/Guix integration in this paper:
>
>  https://hal.inria.fr/hal-01161771/en
>  https://git.savannah.gnu.org/cgit/guix/maintenance.git/tree/doc/reppar-2015/reproducible-hpc.skb
>
> (Note that it starts with ugly ‘%load-path’ hacks.  :-))

Thanks for the reply and the links, good to see another example.

> I would suggest using your own script, executed with ‘guix repl’,
> instead of the ‘skribilo’ executable.  Something like you describe in
> your second message looks good!

I've got the repl approach working without the load path hacks now -
creating an --ad-hoc environment containing both guile and skribilo was
all that was required in the end.  If I can make the approach completely
generic I'll post the code somewhere with an example of use.

What's cool is it is then possible to reference packages without even
having the skribilo document co-located in the same repo as the
packages.  For example if I have a package in guix called "my-package":

(define my-package-str
  (with-output-to-string
    (lambda () (pretty-print (package->code my-package)))))

You can then reference this in skribilo like this:

(prog (source :language scheme my-pacakge-str))

This works great, but I have come-up against one issue I have a proposed
fix for.

package->code uses a function called source->code, to output the
scheme representation of the source.  However source->code assumes that
the source can only be an "origin" record, but it's also valid that
source is a "git-checkout" record.  In particular, if the source repo URL
is an ssh address rather than an https address using git-checkout is the
correct approach - for example:

(source
  (git-checkout
    (url "ssh://git@myserver/foo/bar.git")
    (commit "abcdef12345")))

We make extensive use of this, combined with an ssh-agent, to automate
authentication on private repositories.

Supporting git-checkout in source->code is easy enough - I've written a
fix in our guix channel and it works well, happy to contribute this to
guix-patches too if it makes sense?

The proposed fix can been see here:
https://github.com/quantiletechnologies/qt-guix/commit/49900405617fdf6a2e4ab6f4004306a2770221e0

Finally, I suspect Guix could also be interestingly combined with Haunt
to produce and serve HTML generated from Guix content too:
https://dthompson.us/manuals/haunt/index.html

Cheers,
Phil.