unofficial mirror of guix-devel@gnu.org 
 help / color / mirror / code / Atom feed
From: Phil <phil@beadling.co.uk>
To: guix-devel@gnu.org
Subject: Re: Compile skribilo doc containing guix channel references
Date: Mon, 31 Oct 2022 21:56:35 +0000	[thread overview]
Message-ID: <87a65bac8c.fsf@beadling.co.uk> (raw)
In-Reply-To: <87edup9h0y.fsf@beadling.co.uk>

Hi,

Phil writes:

> My guess is there is a better approach - any suggestions?  Perhaps I can
> call the skribilo compiler from inside "guix repl" for example?

To somewhat answer my own question in case it's useful to anyone else or
if anyone has any suggestion on how to do it better - there are 2 ways
I've found to do this.  The most obvious is to abandon the skribilo DSL
and write the document directly as a scheme file which will evaluate and
write itself out as HTML - it can then be called as: guix repl -- foo.scm:

(with-output-to-file "foo.html"
  (lambda ()
    (evaluate-document d e))))

See skribilo docs for full example.

This isn't ideal because you can't use a the skribe format which isn't
pure scheme.  To do that we have to call the scribilo compiler's main entry
point from inside scheme rather than from the command line - the below
example worked for me, but it's quite fiddly to get it to work.  It is
also called from guix repl.

To give a very simple example the document can use guix functions to
reference infomation in the channel I'm documenting:

(p [The ,(package-name my-package) package is set to ,(package-version my-package).])

The below script has to be one level above the package directory in my
channel, and the script must be called the directory which houses it.

The output should also go to the same directory.  I then moved the
output HTML afterwards, rather than putting the target path in --output
- this makes sure the links work.

The hardcoding of the load-path is also not ideal, I suspect this can be
improved.

(add-to-load-path "/gnu/store/ymvqgkljzykfv4g7vbw36pgghfjbhnps-skribilo-0.9.5/share/guile/site/3.0")
(add-to-load-path "/gnu/store/2160nv245ys30vxvhpjxgcbjm9rq67gw-guile-reader-0.6.3/share/guile/site/3.0")

(define local-repo-clone-path
  (dirname (current-filename)))
 
(define local-packages-clone-path
  (string-append local-repo-clone-path "/packages"))

(add-to-load-path local-packages-clone-path)

(use-modules (skribilo condition))

(call-with-skribilo-error-catch/exit
  (λ ()
    (apply (module-ref (resolve-interface '(skribilo)) 'skribilo)
           `("--target=html"
             ,(string-append "--source-path=" local-packages-clone-path)
             ,(string-append local-repo-clone-path "/docs/my-channel-skribilo-doc.skb")
             "--output=index.html"))))


  reply	other threads:[~2022-10-31 21:57 UTC|newest]

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-10-30 20:46 Compile skribilo doc containing guix channel references Phil
2022-10-31 21:56 ` Phil [this message]
2022-11-02 11:36 ` Ludovic Courtès
2022-11-04 22:13   ` Phil
2022-11-05 16:40     ` Phil
2022-11-05 18:03       ` Ludovic Courtès
2022-11-06 18:50         ` zimoun
2022-11-06 22:12           ` Phil
2022-11-07  8:37             ` zimoun
2022-11-07  9:21           ` Ludovic Courtès
2022-11-07  9:47             ` zimoun
2022-11-10 11:58               ` Ludovic Courtès
2022-11-10 12:39                 ` zimoun
2022-11-17 14:54                   ` Ludovic Courtès
2022-11-05 17:58     ` Ludovic Courtès

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://guix.gnu.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87a65bac8c.fsf@beadling.co.uk \
    --to=phil@beadling.co.uk \
    --cc=guix-devel@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).