Subject: Re: [bug#34515] [PATCH 13/13] gnu: Add Magic-Wormhole.

From: Leo Famulari <[email-masked]>
Date: Mon, 18 Feb 2019 23:55:26 -0500

On Mon, Feb 18, 2019 at 09:51:11AM +0100, Ricardo Wurmus wrote:
> Leo Famulari <[email-masked]> writes:
> > * gnu/packages/magic-wormhole.scm (magic-wormhole): New variable.
> […]
> > +         ;; XXX I can't figure out how to build the docs properly.
> > +         (add-after 'install 'install-docs
> > +           (lambda* (#:key outputs #:allow-other-keys)
> > +             (let* ((out (assoc-ref outputs "out"))
> > +                    (man (string-append out "/share/man/man1")))
> > +               (install-file "docs/wormhole.1" man))
> > +             #t)))))
> 
> What does it mean to build them properly?  Should anything besides the
> man pages be built?

In short, it fails like this:

------
make: Entering directory '/tmp/guix-build-magic-wormhole-0.11.2.drv-0/magic-wormhole-0.11.2/docs'
Running Sphinx v1.7.7
setup.py:20: DeprecationWarning: 'U' mode is deprecated
  long_description=open('README.md', 'rU').read(),
/gnu/store/b7fqhszxl02g6pfm3vw6b3cjz472qrly-python-3.7.0/lib/python3.7/distutils/dist.py:274: UserWarning: Unknown distribution option: 'long_description_content_type'
  warnings.warn(msg)

Configuration error:
There is a programable error in your configuration file:

Traceback (most recent call last):
  File "/gnu/store/q6qyrgr41lqzbray6944l1rs7i6b83kp-python-sphinx-1.7.7/lib/python3.7/site-packages/sphinx/config.py", line 161, in __init__
    execfile_(filename, config)
  File "/gnu/store/q6qyrgr41lqzbray6944l1rs7i6b83kp-python-sphinx-1.7.7/lib/python3.7/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "conf.py", line 70, in <module>
    version, release = _get_versions()
  File "conf.py", line 67, in _get_versions
    short = ".".join(v.split(".")[:2])
TypeError: a bytes-like object is required, not 'str'

make: *** [Makefile:20: man] Error 2
make: Leaving directory '/tmp/guix-build-magic-wormhole-0.11.2.drv-0/magic-wormhole-0.11.2/docs'
------

Using the patch under discussion, only a pre-built manual page is
installed.

There is apparently a build script that uses Sphinx to build a more full
set of manual pages, from markdown source files. This documentation
would discuss the design and implementation of Magic-Wormhole, and it
would be nice to have.

With the attached patch, the problem can be reproduced, and I've
reported it upstream here:

https://github.com/warner/magic-wormhole/issues/321

> > +    (native-inputs
> > +     `(("python-mock" ,python-mock)
> > +       ;; XXX These are required for the test suite but end up being referenced
> > +       ;; by the built package.
> > +       ("magic-wormhole-mailbox-server" ,magic-wormhole-mailbox-server)
> > +       ("magic-wormhole-transit-relay" ,magic-wormhole-transit-relay)))
> 
> Are they not supposed to be referenced by the built package?
> If they are supposed to be used by the built package is it enough to
> have them as inputs and not as propagated inputs?

In this case they are actually native-inputs, not propagated-inputs. But
they still end up on the PYTHONPATHs in the built package, so they are
referenced.

I don't believe they are used by the magic-wormhole program except in
client-server way over the network. They shouldn't need to be part of
the closure of magic-wormhole.
diff --git a/gnu/packages/magic-wormhole.scm b/gnu/packages/magic-wormhole.scm
index 4f8fabd1c5..80e707a3e2 100644
--- a/gnu/packages/magic-wormhole.scm
+++ b/gnu/packages/magic-wormhole.scm
@@ -117,17 +117,20 @@ together, allowing them to pretend they have a direct connection.")
           "01fr4bi6kc6fz9n3c4qq892inrc3nf6p2djy65yvm7xkvdxncydf"))))
     (build-system python-build-system)
     (arguments
-     '(#:phases
+     '(#:tests? #f ; to speed up debugging the documentation build failure
+       #:phases
        (modify-phases %standard-phases
          ;; XXX I can't figure out how to build the docs properly.
          (add-after 'install 'install-docs
            (lambda* (#:key outputs #:allow-other-keys)
              (let* ((out (assoc-ref outputs "out"))
                     (man (string-append out "/share/man/man1")))
-               (install-file "docs/wormhole.1" man))
-             #t)))))
+               (invoke "make" "-C" "docs" "man")
+             #t))))))
     (native-inputs
      `(("python-mock" ,python-mock)
+       ("python-sphinx" ,python-sphinx)
+       ("python-recommonmark" ,python-recommonmark)
        ;; XXX These are required for the test suite but end up being referenced
        ;; by the built package.
        ("magic-wormhole-mailbox-server" ,magic-wormhole-mailbox-server)
@@ -156,3 +159,68 @@ wordlist.  The receiving side offers tab-completion on the codewords, so usually
 only a few characters must be typed.  Wormhole codes are single-use and do not
 need to be memorized.")
     (license expat)))
+
+(define-public python-commonmark
+  (package
+    (name "python-commonmark")
+    (version "0.8.1")
+    (source
+      (origin
+        (method url-fetch)
+        (uri (pypi-uri "commonmark" version))
+        (sha256
+          (base32
+            "1130029ykz4jny5sr65zb03lm2xp062k4pmfaapxxrgaw1acijxb"))))
+    (build-system python-build-system)
+    (arguments
+     `(#:phases
+       (modify-phases %standard-phases
+         ;; have to delete and recreate check?
+         (delete 'check)
+         (add-after 'install 'check
+                    ;; inputs and outputs?
+           (lambda* (#:key inputs outputs #:allow-other-keys)
+             (add-installed-pythonpath inputs outputs)
+             (invoke "python" "setup.py" "test"))))
+       )
+      )
+    (propagated-inputs
+     `(
+        ("python-flake8" ,python-flake8)
+        ("python-future" ,python-future)
+        ("python-hypothesis" ,python-hypothesis)
+        ))
+    (home-page
+      "https://github.com/rtfd/CommonMark-py")
+    (synopsis
+      "Python parser for the CommonMark Markdown spec")
+    (description
+      "Python parser for the CommonMark Markdown spec")
+    (license bsd-3)))
+
+(define-public python-recommonmark
+  (package
+    (name "python-recommonmark")
+    (version "0.5.0")
+    (source
+      (origin
+        (method url-fetch)
+        (uri (pypi-uri "recommonmark" version))
+        (sha256
+          (base32
+            "0j5vylbhdddjhc6kj4y9pm8pyf7yy9965kr77bi1m9bia39bh855"))))
+    (build-system python-build-system)
+    (arguments
+     '(#:tests? #f)) ; fail mysteriously...
+    (propagated-inputs
+      `(("python-commonmark" ,python-commonmark)
+        ("python-docutils" ,python-docutils)
+        ("python-sphinx" ,python-sphinx)))
+    (home-page
+      "https://github.com/rtfd/recommonmark")
+    (synopsis
+      "A docutils-compatibility bridge to CommonMark, enabling you to write CommonMark inside of Docutils & Sphinx projects.")
+    (description
+      "A docutils-compatibility bridge to CommonMark, enabling you to write CommonMark inside of Docutils & Sphinx projects.")
+    (license expat)))
+