[PATCH 0/5] Install docs for Let's Encrypt

[PATCH 0/5] Install docs for Let's Encrypt

[Leo Famulari]

These patches add what's needed to build info files and manpages for
letsencrypt and python-acme.

I'd appreciate some feedback on the 'docs' phases added to letsencrypt
and python-acme. Specifically, is my use of (and) correct?

Leo Famulari (5):
  gnu: Add python-sphinxcontrib-programoutput.
  licenses: Add repoze license.
  gnu: Add python-sphinx-repoze-autointerface.
  gnu: letsencrypt: Generate and install documentation.
  gnu: python-acme: Generate and install documentation.

 gnu/packages/python.scm | 54 ++++++++++++++++++++++++++++++++++++++++++++++++-
 gnu/packages/tls.scm    | 47 ++++++++++++++++++++++++++++++++++++------
 guix/licenses.scm       |  7 +++++++
 3 files changed, 101 insertions(+), 7 deletions(-)

-- 
2.6.3

[PATCH 1/5] gnu: Add python-sphinxcontrib-programoutput.

[Leo Famulari]

* gnu/packages/python.scm (python-sphinxcontrib-programoutput,
python2-sphinxcontrib-programoutput): New variables.
---
 gnu/packages/python.scm | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/gnu/packages/python.scm b/gnu/packages/python.scm
index 24af2d8..6795c95 100644
--- a/gnu/packages/python.scm
+++ b/gnu/packages/python.scm
@@ -7561,3 +7561,30 @@ templates into Python modules.")
       (native-inputs
        (cons `("python2-setuptools" ,python2-setuptools)
              (package-native-inputs base))))))
+
+(define-public python-sphinxcontrib-programoutput
+  (package
+    (name "python-sphinxcontrib-programoutput")
+    (version "0.8")
+    (source (origin
+              (method url-fetch)
+              (uri (pypi-uri "sphinxcontrib-programoutput" version))
+              (sha256
+               (base32
+                "098as6z1s0gb4dh5xcr1fd2vpm91zj93jzvgawspxf5s4hqs0xhp"))))
+    (build-system python-build-system)
+    (propagated-inputs
+     `(("python-docutils" ,python-docutils)
+       ("python-sphinx" ,python-sphinx)))
+    (synopsis "Sphinx extension to include program output")
+    (description "A Sphinx extension to literally insert the output of arbitrary
+commands into documents, helping you to keep your command examples up to date.")
+    (home-page "https://github.com/lunaryorn/sphinxcontrib-programoutput")
+    (license bsd-2)
+    (properties `((python2-variant . ,(delay python2-sphinxcontrib-programoutput))))))
+
+(define-public python2-sphinxcontrib-programoutput
+  (package
+    (inherit (package-with-python2
+              (strip-python2-variant python-sphinxcontrib-programoutput)))
+    (native-inputs `(("python2-setuptools" ,python2-setuptools)))))
-- 
2.6.3

[PATCH 2/5] licenses: Add repoze license.

[Leo Famulari]

* guix/licenses.scm (repoze): New variable.
---
 guix/licenses.scm | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/guix/licenses.scm b/guix/licenses.scm
index 1abb0a1..e892127 100644
--- a/guix/licenses.scm
+++ b/guix/licenses.scm
@@ -59,6 +59,7 @@
             openldap2.8 openssl
             psfl public-domain
             qpl
+            repoze
             ruby
             sgifreeb2.0
             silofl1.1
@@ -369,6 +370,12 @@ at URI, which may be a file:// URI pointing the package's tree."
            "http://directory.fsf.org/wiki/License:QPLv1.0"
            "http://www.gnu.org/licenses/license-list.html#QPL"))
 
+(define repoze
+  (license "Repoze"
+           "http://repoze.org/LICENSE.txt"
+           "A BSD-like license with a clause requiring all changes to be
+           attributed by author and date."))
+
 (define ruby
   (license "Ruby License"
            "http://directory.fsf.org/wiki/License:Ruby"
-- 
2.6.3

[PATCH 3/5] gnu: Add python-sphinx-repoze-autointerface.

[Leo Famulari]

* gnu/packages/python.scm (python-sphinx-repoze-autointerface,
python2-sphinx-repoze-autointerface): New variables.
---
 gnu/packages/python.scm | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/gnu/packages/python.scm b/gnu/packages/python.scm
index 6795c95..6db11ac 100644
--- a/gnu/packages/python.scm
+++ b/gnu/packages/python.scm
@@ -37,7 +37,7 @@
   #:use-module ((guix licenses)
                 #:select (asl2.0 bsd-4 bsd-3 bsd-2 non-copyleft cc0 x11 x11-style
                           gpl2 gpl2+ gpl3+ lgpl2.0+ lgpl2.1 lgpl2.1+ lgpl3+ agpl3+
-                          isc mpl2.0 psfl public-domain unlicense x11-style
+                          isc mpl2.0 psfl public-domain repoze unlicense x11-style
                           zpl2.1))
   #:use-module ((guix licenses) #:select (expat zlib) #:prefix license:)
   #:use-module (gnu packages)
@@ -7588,3 +7588,28 @@ commands into documents, helping you to keep your command examples up to date.")
     (inherit (package-with-python2
               (strip-python2-variant python-sphinxcontrib-programoutput)))
     (native-inputs `(("python2-setuptools" ,python2-setuptools)))))
+
+(define-public python-sphinx-repoze-autointerface
+  (package
+    (name "python-sphinx-repoze-autointerface")
+    (version "0.7.1")
+    (source (origin
+              (method url-fetch)
+              (uri (pypi-uri "repoze.sphinx.autointerface" version))
+              (sha256
+               (base32
+                "016mv3wbylw278wl7z33y2liyra8ljp08zq1g0anzadh1an5zvwp"))))
+    (build-system python-build-system)
+    (propagated-inputs
+     `(("python-docutils" ,python-docutils)
+       ("python-sphinx" ,python-sphinx)
+       ("python-zope-interface" ,python-zope-interface)))
+    (synopsis "Auto-generate Sphinx API docs from Zope interfaces")
+    (description "Thie package defines an extension for the Sphinx documentation
+system.  The extension allows generation of API documentation by
+introspection of @code{zope.interface} instances in code.")
+    (home-page "https://github.com/repoze/repoze.sphinx.autointerface")
+    (license repoze)))
+
+(define-public python2-sphinx-repoze-autointerface
+  (package-with-python2 python-sphinx-repoze-autointerface))
-- 
2.6.3

Re: [PATCH 3/5] gnu: Add python-sphinx-repoze-autointerface.

[Alex Kost]

Leo Famulari (2016-02-18 06:53 +0300) wrote:

> * gnu/packages/python.scm (python-sphinx-repoze-autointerface,
> python2-sphinx-repoze-autointerface): New variables.
> ---
>  gnu/packages/python.scm | 27 ++++++++++++++++++++++++++-
>  1 file changed, 26 insertions(+), 1 deletion(-)

[...]
> +    (synopsis "Auto-generate Sphinx API docs from Zope interfaces")
> +    (description "Thie package defines an extension for the Sphinx documentation
typo -------------------^

-- 
Alex

Re: [PATCH 3/5] gnu: Add python-sphinx-repoze-autointerface.

[Leo Famulari]

On Thu, Feb 18, 2016 at 11:28:52AM +0300, Alex Kost wrote:
> Leo Famulari (2016-02-18 06:53 +0300) wrote:
> 
> > * gnu/packages/python.scm (python-sphinx-repoze-autointerface,
> > python2-sphinx-repoze-autointerface): New variables.
> > ---
> >  gnu/packages/python.scm | 27 ++++++++++++++++++++++++++-
> >  1 file changed, 26 insertions(+), 1 deletion(-)
> 
> [...]
> > +    (synopsis "Auto-generate Sphinx API docs from Zope interfaces")
> > +    (description "Thie package defines an extension for the Sphinx documentation
> typo -------------------^

Good eye, thanks!

> 
> -- 
> Alex

[PATCH 4/5] gnu: letsencrypt: Generate and install documentation.

[Leo Famulari]

* gnu/packages/tls.scm (letsencrypt)[arguments]: Add 'docs' phase.
[native-inputs]: Add python2-sphinx, python2-sphinx-rtd-theme,
python2-sphinx-repoze-autointerface,
python2-sphinxcontrib-programoutput, texinfo.
---
 gnu/packages/tls.scm | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/gnu/packages/tls.scm b/gnu/packages/tls.scm
index 3aca5f3..00d4805 100644
--- a/gnu/packages/tls.scm
+++ b/gnu/packages/tls.scm
@@ -375,11 +375,33 @@ security, and applying best practice development processes.")
                 "1wwq8yvfdybf4d0gv4yfddkrg865s7rhng5xg563kks4wza1a2wp"))))
     (build-system python-build-system)
     (arguments
-     `(#:python ,python-2))
-    ;; TODO: Add optional inputs for testing building documentation.
+     `(#:python ,python-2
+       #:phases
+       (modify-phases %standard-phases
+         (add-after 'install 'docs
+           (lambda* (#:key outputs #:allow-other-keys)
+             (let* ((out (assoc-ref outputs "out"))
+                    (man1 (string-append out "/share/man/man1"))
+                    (man7 (string-append out "/share/man/man7"))
+                    (info (string-append out "/info")))
+               (substitute* "docs/man/letsencrypt.rst"
+                 (("letsencrypt --help all")
+                  (string-append out "/bin/letsencrypt" " --help all")))
+               (and
+                 (zero? (system* "make" "-C" "docs" "man" "info"))
+                 (install-file "docs/_build/texinfo/LetsEncrypt.info" info)
+                 (install-file "docs/_build/man/letsencrypt.1" man1)
+                 (install-file "docs/_build/man/letsencrypt.7" man7))))))))
+    ;; TODO: Add optional inputs for testing.
     (native-inputs
      `(("python2-nose" ,python2-nose)
-       ("python2-mock" ,python2-mock)))
+       ("python2-mock" ,python2-mock)
+       ;; For documentation
+       ("python2-sphinx" ,python2-sphinx)
+       ("python2-sphinx-rtd-theme" ,python2-sphinx-rtd-theme)
+       ("python2-sphinx-repoze-autointerface" ,python2-sphinx-repoze-autointerface)
+       ("python2-sphinxcontrib-programoutput" ,python2-sphinxcontrib-programoutput)
+       ("texinfo" ,texinfo)))
     (propagated-inputs
      `(("python2-acme" ,python2-acme)
        ("python2-zope-interface" ,python2-zope-interface)
-- 
2.6.3

[PATCH 5/5] gnu: python-acme: Generate and install documentation.

[Leo Famulari]

* gnu/packages/tls.scm (acme)[arguments]: Add 'docs' phase.
[native-inputs]: Add python-sphinx, python-sphinxcontrib-programoutput,
python-sphinx-rtd-theme, python-setuptools, texinfo.
---
 gnu/packages/tls.scm | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/gnu/packages/tls.scm b/gnu/packages/tls.scm
index 00d4805..dc6f9b4 100644
--- a/gnu/packages/tls.scm
+++ b/gnu/packages/tls.scm
@@ -340,11 +340,24 @@ security, and applying best practice development processes.")
                (display "\n[easy_install]\nzip_ok = 0\n"
                         port)
                (close-port port)
-               #t))))))
-    ;; TODO: Add optional inputs for testing and building documentation.
+               #t)))
+         (add-after 'install 'docs
+           (lambda* (#:key outputs #:allow-other-keys)
+             (let* ((out (assoc-ref outputs "out"))
+                    (man (string-append out "/share/man/man1"))
+                    (info (string-append out "/info")))
+               (and (zero? (system* "make" "-C" "docs" "man" "info"))
+                    (install-file "docs/_build/texinfo/acme-python.info" info)
+                    (install-file "docs/_build/man/acme-python.1" man))))))))
+    ;; TODO: Add optional inputs for testing.
     (native-inputs
      `(("python-mock" ,python-mock)
-       ("python-setuptools" ,python-setuptools)))
+       ;; For documentation
+       ("python-sphinx" ,python-sphinx)
+       ("python-sphinxcontrib-programoutput" ,python-sphinxcontrib-programoutput)
+       ("python-sphinx-rtd-theme" ,python-sphinx-rtd-theme)
+       ("python-setuptools" ,python-setuptools)
+       ("texinfo" ,texinfo)))
     (propagated-inputs
      `(("python-ndg-httpsclient" ,python-ndg-httpsclient)
        ("python-werkzeug" ,python-werkzeug)
-- 
2.6.3

Re: [PATCH 5/5] gnu: python-acme: Generate and install documentation.

[Ricardo Wurmus]

Leo Famulari <leo@famulari.name> writes:

> * gnu/packages/tls.scm (acme)[arguments]: Add 'docs' phase.
> [native-inputs]: Add python-sphinx, python-sphinxcontrib-programoutput,
> python-sphinx-rtd-theme, python-setuptools, texinfo.
> ---
>  gnu/packages/tls.scm | 19 ++++++++++++++++---
>  1 file changed, 16 insertions(+), 3 deletions(-)
>
> diff --git a/gnu/packages/tls.scm b/gnu/packages/tls.scm
> index 00d4805..dc6f9b4 100644
> --- a/gnu/packages/tls.scm
> +++ b/gnu/packages/tls.scm
> @@ -340,11 +340,24 @@ security, and applying best practice development processes.")
>                 (display "\n[easy_install]\nzip_ok = 0\n"
>                          port)
>                 (close-port port)
> -               #t))))))
> -    ;; TODO: Add optional inputs for testing and building documentation.
> +               #t)))
> +         (add-after 'install 'docs
> +           (lambda* (#:key outputs #:allow-other-keys)
> +             (let* ((out (assoc-ref outputs "out"))
> +                    (man (string-append out "/share/man/man1"))
> +                    (info (string-append out "/info")))
> +               (and (zero? (system* "make" "-C" "docs" "man" "info"))
> +                    (install-file "docs/_build/texinfo/acme-python.info" info)
> +                    (install-file "docs/_build/man/acme-python.1" man))))))))

“install-file” calls “copy-file” last and according to the Guile manual
the return value of “copy-file” is unspecified.  In practise this is not
#f, of course, so all the three arguments to “(and ...)” will be
evaluated as long as “make” does not fail.

However, “and” just returns the return value of its last argument
(unless one of the arguments evaluates to “#f”), which is unspecified,
not “#t”.  As we want successful phases to return “#t” you could
explicitly add “#t” as a fourth argument to “(and ...)”.

Not sure if that’s really necessary, but you did ask for comments about
your use of “and”... :)

~~ Ricardo

Re: [PATCH 5/5] gnu: python-acme: Generate and install documentation.

[Leo Famulari]

On Thu, Feb 18, 2016 at 01:51:40PM +0100, Ricardo Wurmus wrote:
> 
> Leo Famulari <leo@famulari.name> writes:
> 
> > * gnu/packages/tls.scm (acme)[arguments]: Add 'docs' phase.
> > [native-inputs]: Add python-sphinx, python-sphinxcontrib-programoutput,
> > python-sphinx-rtd-theme, python-setuptools, texinfo.
> > ---
> >  gnu/packages/tls.scm | 19 ++++++++++++++++---
> >  1 file changed, 16 insertions(+), 3 deletions(-)
> >
> > diff --git a/gnu/packages/tls.scm b/gnu/packages/tls.scm
> > index 00d4805..dc6f9b4 100644
> > --- a/gnu/packages/tls.scm
> > +++ b/gnu/packages/tls.scm
> > @@ -340,11 +340,24 @@ security, and applying best practice development processes.")
> >                 (display "\n[easy_install]\nzip_ok = 0\n"
> >                          port)
> >                 (close-port port)
> > -               #t))))))
> > -    ;; TODO: Add optional inputs for testing and building documentation.
> > +               #t)))
> > +         (add-after 'install 'docs
> > +           (lambda* (#:key outputs #:allow-other-keys)
> > +             (let* ((out (assoc-ref outputs "out"))
> > +                    (man (string-append out "/share/man/man1"))
> > +                    (info (string-append out "/info")))
> > +               (and (zero? (system* "make" "-C" "docs" "man" "info"))
> > +                    (install-file "docs/_build/texinfo/acme-python.info" info)
> > +                    (install-file "docs/_build/man/acme-python.1" man))))))))
> 
> “install-file” calls “copy-file” last and according to the Guile manual
> the return value of “copy-file” is unspecified.  In practise this is not
> #f, of course, so all the three arguments to “(and ...)” will be
> evaluated as long as “make” does not fail.
> 
> However, “and” just returns the return value of its last argument
> (unless one of the arguments evaluates to “#f”), which is unspecified,
> not “#t”.  As we want successful phases to return “#t” you could
> explicitly add “#t” as a fourth argument to “(and ...)”.
> 
> Not sure if that’s really necessary, but you did ask for comments about
> your use of “and”... :)

Thanks for taking the time to write this!

I didn't realize that copy-file's return value is unspecified. I've
found that it does tend to make the whole build fail when the source
file doesn't exist, so it must be returning #f in that case, right?

In any case, I can't rely on it if it's unspecified.

I wouldn't be surprised if "make" fails the next time this is updated —
the process seems rather complicated *and* untested. Since I don't want
to proceed if make fails I guess that I should use (and ...), and
explicity return #t from the function. What do you think?

Re: [PATCH 5/5] gnu: python-acme: Generate and install documentation.

[Andreas Enge]

On Thu, Feb 18, 2016 at 12:46:50PM -0500, Leo Famulari wrote:
> I didn't realize that copy-file's return value is unspecified. I've
> found that it does tend to make the whole build fail when the source
> file doesn't exist, so it must be returning #f in that case, right?

Not necessarily. Many things with side-effects just fail with an error
when there is a problem. So in many cases, the question of whether one
needs to explicitly return #t in the end is mainly aesthetic.

Andreas

Re: [PATCH 0/5] Install docs for Let's Encrypt

[Leo Famulari]

On Wed, Feb 17, 2016 at 10:53:48PM -0500, Leo Famulari wrote:
> These patches add what's needed to build info files and manpages for
> letsencrypt and python-acme.
> 
> I'd appreciate some feedback on the 'docs' phases added to letsencrypt
> and python-acme. Specifically, is my use of (and) correct?

If there are no more comments, I'll incorporate my reviewers' helpful
comments and push in the next day or so.

> 
> Leo Famulari (5):
>   gnu: Add python-sphinxcontrib-programoutput.
>   licenses: Add repoze license.
>   gnu: Add python-sphinx-repoze-autointerface.
>   gnu: letsencrypt: Generate and install documentation.
>   gnu: python-acme: Generate and install documentation.
> 
>  gnu/packages/python.scm | 54 ++++++++++++++++++++++++++++++++++++++++++++++++-
>  gnu/packages/tls.scm    | 47 ++++++++++++++++++++++++++++++++++++------
>  guix/licenses.scm       |  7 +++++++
>  3 files changed, 101 insertions(+), 7 deletions(-)
> 
> -- 
> 2.6.3
>