[bug#57280] [PATCH 0/3] Add documentation-files argument to emacs build system.

[Andrew Tropin]

On 2022-08-30 10:28, Liliana Marie Prikler wrote:

> Am Dienstag, dem 30.08.2022 um 11:15 +0300 schrieb Andrew Tropin:
>> On 2022-08-29 18:38, Liliana Marie Prikler wrote:
>> 
>> > Am Freitag, dem 26.08.2022 um 17:33 +0300 schrieb Andrew Tropin:
>> > 
>> > > > > > 
>> > > > Cheers
>> > > 
>> > > I went through a few popular packages and came up with conclusion
>> > > that it's hard to make good heuristic for automatical
>> > > documentation
>> > > build:
>> > > 
>> > > 1. I tried (find-files "." "\\.(texi|txi|texinfo)$") with
>> > > consequent
>> > > for-each and it doesn't work in general case because it will
>> > > build
>> > > files intended for inclusion, not standalone building.
>> > Fair enough, there's probably similar issues with org etc.  That
>> > said,
>> > wouldn't the top-level info/org/whatever file share the package
>> > name?
>> > 
>> 
>> In many cases, yes it would, but not always.
>> 
>> magit: ("docs/magit.texi" "docs/magit-section.texi")
> Is magit-section a top-level file?

Yes.  In 3.3.0 it's Documentation/magit.texi and
Documentation/magit-section.texi, but in recent not yet released
version it's ("docs/magit.texi" "docs/magit-section.texi"), there are
also org counterparts of magit and magit-section files, but they are in
sync with texi files.

>
>> geiser: ("doc/geiser.texi")
> I think trying docs?/whatever is good praxis, so I count that as a hit.
>
>> geiser-guile: ("geiser-guile.texi")
> Hit.
>
>> dash: ("dash.texi")
> Hit.
>
>> orderless: ("orderless.texi")
> Hit.
>
>> consult/cape/tempel: ("README.org")
> Hit for README.whatever
>
>> cider: ("doc/modules/ROOT/nav.adoc")
> Miss.
>
>> all-the-icons: ("README.md")
> Hit for README.whatever
>
>> citar: ("README.org")
> Hit for README.whatever
>
>> org-roam: ("doc/org-roam.texi")
> Hit.
>
>> debbugs: ("debbugs.texi" "debbugs-ug.texi")
> Is debbugs-ug a top-level file?

Yes, the second one is User Guide.

>
>> modus-themes: ("doc/modus-themes.org")
> Hit.
>
>> > 
>> > 
>> > > It seems that manual approach is more precise, less intrusive and
>> > > helps to get rid of many custom and non-uniform documentation
>> > > build
>> > > phases.
>> > If you're going for a "manual" approach, I'd suggest instead making
>> > a curried ((build-documentation #:texinfo-files #:texinfo-regexp
>> > ...)
>> > #:outputs ...) so that the files can be written directly into the
>> > (add-after ...) syntax.
>> 
>> Do you mean to make a helper function, which can be used to generate
>> a closure of build phase, which can be added with replace/add-after?
>> 
>> Another idea is to make a separate functions for different
>> documentation
>> type: build-{texinfo,markdown,org,etc}-documentation.  Also, it seems
>> useful outside of emacs-build-system as well.
> Hmm, if we wanted to make that even more generic than just emacs, it'd
> go to core-updates.  
>
>> In such case user will need to accomplish following steps: 1. add
>> texinfo/pandoc/emacs-org dependency 2. use modify-phases to add
>> (build-{texinfo,whatever}-documentation #:texinfo-files
>> '("doc/manual.{texi,whatever}")), seems a little less convenient than
>> simple #:documentation-files #~(list "manual.{texi,whatever}"), but
>> also work, at least documentation will be built more uniformly for
>> different packages.
>> 
>> WDYT?
> I think if we want to go this more generic route, we'd have to redesign
> this a little.  For instance, (build-texinfo-documentation) should take
> regular expressions as remaining arguments.  

What can be a good place (module) for such build phases?

> As for the native-inputs required, there has already been a precedent
> set with bash-minimal that anything requiring extraneous inputs needs
> to declare them explicitly.

I think it will work, need to experiment with (build-*-documentation) to
get the feeling.


Attaching the latest version of the documentation-files patch I have:

From a1534b2158c97986e1048379661ee9d250ad6c02 Mon Sep 17 00:00:00 2001
From: Andrew Tropin <andrew@trop.in>
Date: Thu, 18 Aug 2022 17:43:14 +0300
Subject: [PATCH v2 1/2] build-system: emacs: Add documentation-files argument.

Allows to build info files from texinfo or org.

* guix/build-system/emacs.scm (default-texinfo): New variable.
* guix/build-system/emacs.scm (lower): New arguments.
* guix/build/emacs-build-system.scm (generate-docs): New variable.
---
 guix/build-system/emacs.scm       | 16 ++++++++++++++--
 guix/build/emacs-build-system.scm | 22 ++++++++++++++++++++++
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/guix/build-system/emacs.scm b/guix/build-system/emacs.scm
index 3df68789ff..02379ee54c 100644
--- a/guix/build-system/emacs.scm
+++ b/guix/build-system/emacs.scm
@@ -56,8 +56,16 @@ (define (default-emacs)
   (let ((emacs-mod (resolve-interface '(gnu packages emacs))))
     (module-ref emacs-mod 'emacs-minimal)))
 
+(define (default-texinfo)
+  "Return the default texinfo package."
+  ;; Lazily resolve the binding to avoid a circular dependency.
+  (let ((texinfo-mod (resolve-interface '(gnu packages texinfo))))
+    (module-ref texinfo-mod 'texinfo)))
+
 (define* (lower name
                 #:key source inputs native-inputs outputs system target
+                documentation-files
+                (texinfo (default-texinfo))
                 (emacs (default-emacs))
                 #:allow-other-keys
                 #:rest arguments)
@@ -76,8 +84,10 @@ (define private-keywords
 
                         ;; Keep the standard inputs of 'gnu-build-system'.
                         ,@(standard-packages)))
-         (build-inputs `(("emacs" ,emacs)
-                         ,@native-inputs))
+         (build-inputs `(,@native-inputs
+                         ("emacs" ,emacs)
+                         ;; ,@(if (null? documentation-files) '() )
+                         ("texinfo" ,texinfo)))
          (outputs outputs)
          (build emacs-build)
          (arguments (strip-keyword-arguments private-keywords arguments)))))
@@ -87,6 +97,7 @@ (define* (emacs-build name inputs
                       (tests? #f)
                       (parallel-tests? #t)
                       (test-command ''("make" "check"))
+                      (documentation-files ''())
                       (phases '%standard-phases)
                       (outputs '("out"))
                       (include (quote %default-include))
@@ -109,6 +120,7 @@ (define builder
                        #:test-command #$test-command
                        #:tests? #$tests?
                        #:parallel-tests? #$parallel-tests?
+                       #:documentation-files #$documentation-files
                        #:phases #$phases
                        #:outputs #$(outputs->gexp outputs)
                        #:include #$include
diff --git a/guix/build/emacs-build-system.scm 
b/guix/build/emacs-build-system.scm
index 6a6918bfdd..3ffa196862 100644
--- a/guix/build/emacs-build-system.scm
+++ b/guix/build/emacs-build-system.scm
@@ -274,6 +274,27 @@ (define (match-stripped-file action regex)
                            (install-file? file stat #:verbose? #t)))
       #f))))
 
+(define* (generate-documentation
+          #:key outputs documentation-files
+          #:allow-other-keys)
+  "Convert texinfo or org files specified in DOCUMENTATION-FILES argument to
+info files.  And move info files site-lisp directory."
+  (for-each (lambda (f)
+              (if (regexp-exec
+                   (make-regexp "\\.(txi|texi|texinfo)" regexp/icase)
+                   f)
+                  (invoke "makeinfo" f)
+                  (emacs-batch-script ; else org file
+                   `(progn
+                     (require 'ox-texinfo)
+                     (find-file ,f)
+                     (org-texinfo-export-to-info)))))
+            documentation-files)
+  (for-each (lambda (f)
+              (install-file f (string-append (assoc-ref outputs "out")
+                                             %install-dir)))
+            (find-files "." "\\.info$")))
+
 (define* (move-doc #:key outputs #:allow-other-keys)
   "Move info files from the ELPA package directory to the info directory."
   (let* ((out (assoc-ref outputs "out"))
@@ -343,6 +364,7 @@ (define %standard-phases
   (modify-phases gnu:%standard-phases
     (replace 'unpack unpack)
     (add-after 'unpack 'expand-load-path expand-load-path)
+    (add-after 'expand-load-path 'generate-documentation 
generate-documentation)
     (delete 'bootstrap)
     (delete 'configure)
     (delete 'build)
-- 
2.37.2

From 8adbef898ef80851753ba9d64b31eed727bb34de Mon Sep 17 00:00:00 2001
From: Andrew Tropin <andrew@trop.in>
Date: Wed, 31 Aug 2022 12:16:10 +0300
Subject: [PATCH v2 2/2] gnu: emacs-xyz: Add documentation-files example usage.

* gnu/packages/emacs-xyz.scm (emacs-geiser, emacs-geiser-guile, emacs-magit,
emacs-dash, emacs-consult, emacs-tempel): Add documentation-files example
usage.
---
 gnu/packages/emacs-xyz.scm | 26 ++++++++++----------------
 1 file changed, 10 insertions(+), 16 deletions(-)

diff --git a/gnu/packages/emacs-xyz.scm b/gnu/packages/emacs-xyz.scm
index 90ee485f1e..df0570a4a1 100644
--- a/gnu/packages/emacs-xyz.scm
+++ b/gnu/packages/emacs-xyz.scm
@@ -262,7 +262,8 @@ (define-public emacs-geiser
         (base32 "1pm33zlcq84h61xhplmrlicckrax1pv39zrmv8ryzhi9mqrb6bdg"))))
     (build-system emacs-build-system)
     (arguments
-     '(#:phases
+     '(#:documentation-files (list "doc/geiser.texi")
+       #:phases
        (modify-phases %standard-phases
          ;; Move the source files to the top level, which is included in
          ;; the EMACSLOADPATH.
@@ -271,12 +272,7 @@ (define-public emacs-geiser
              (let ((el-files (find-files "./elisp" ".*\\.el$")))
                (for-each (lambda (f)
                            (rename-file f (basename f)))
-                         el-files))))
-         (add-before 'install 'make-info
-           (lambda _
-             (with-directory-excursion "doc"
-               (invoke "makeinfo" "--no-split"
-                       "-o" "geiser.info" "geiser.texi")))))))
+                         el-files)))))))
     (native-inputs
      (list texinfo))
     (home-page "https://www.nongnu.org/geiser/";)
@@ -311,6 +307,7 @@ (define-public emacs-geiser-guile
     (arguments
      (list
       #:include #~(cons "^src/" %default-include)
+      #:documentation-files #~(list "geiser-guile.texi")
       #:phases
       #~(modify-phases %standard-phases
           (add-after 'unpack 'patch-geiser-guile-binary
@@ -978,17 +975,11 @@ (define-public emacs-magit
       #:exclude #~(cons* "magit-libgit.el"
                          "magit-libgit-pkg.el"
                          %default-exclude)
+      #:documentation-files #~(list "Documentation/magit.texi"
+                                    "Documentation/magit-section.texi")
       #:phases
       #~(modify-phases %standard-phases
-          (add-after 'unpack 'build-info-manual
-            (lambda _
-              (invoke "make" "info")
-              ;; Copy info files to the lisp directory, which acts as
-              ;; the root of the project for the emacs-build-system.
-              (for-each (lambda (f)
-                          (install-file f "lisp"))
-                        (find-files "Documentation" "\\.info$"))))
-          (add-after 'build-info-manual 'set-magit-version
+          (add-after 'unpack 'set-magit-version
             (lambda _
               (make-file-writable "lisp/magit.el")
               (emacs-substitute-variables "lisp/magit.el"
@@ -3909,6 +3900,7 @@ (define-public emacs-dash
     (build-system emacs-build-system)
     (arguments
      (list #:tests? #t
+           #:documentation-files #~(list "dash.texi")
            #:phases
            #~(modify-phases %standard-phases
                (add-after 'unpack 'disable-byte-compile-error-on-warn
@@ -9188,6 +9180,7 @@ (define-public emacs-consult
        (sha256
         (base32 "0sy4rn1vjk1g50r8z14hzj8lds6s7ij2zkjqfi6mfash5il75wnq"))
        (file-name (git-file-name name version))))
+    (arguments (list #:documentation-files #~(list "README.org")))
     (build-system emacs-build-system)
     (propagated-inputs (list emacs-compat))
     (home-page "https://github.com/minad/consult";)
@@ -14145,6 +14138,7 @@ (define-public emacs-tempel
                (base32
                 "0iyh6wxchqg83gpwvg6lz4qy4c2qh25iqjpjm56kif52346a99d2"))))
     (build-system emacs-build-system)
+    (arguments (list #:documentation-files #~(list "README.org")))
     (home-page "https://github.com/minad/tempel";)
     (synopsis "Simple templates for Emacs")
     (description
-- 
2.37.2

-- 
Best regards,
Andrew Tropin

signature.asc
Description: PGP signature