who finds support for rst2man in the notmuch build process useful?

who finds support for rst2man in the notmuch build process useful?

[David Bremner]

[-- Attachment #1: Type: text/plain, Size: 775 bytes --]


Recently in discussion of at

         id:1420300167-5060-1-git-send-email-david@tethera.net

it was proposed we could just eliminate support for non-sphinx based
methods of building the docs. This would require sphinx >= 1.0 and
python-docutils 0.6 to build the docs.

The win for us would be to eliminate some custom python scripting in the
build process to fake some small part of sphinx functionality; it would
also allow us to use more features of sphinx in the .rst source.

Version 1.0 of sphinx is from 2010, and is present e.g. in Debian
stable.

We are having a bit of dependency creep here. One option would be to
generate seperate tarballs of the pre-formatted man pages during the
release process; this _should_ be a matter of running "tar" on the build
tree.


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 647 bytes --]

[PATCH] doc: remove support for rst2man

[David Bremner]

It was becoming increasingly complicated to support rst2man, and there
were apparently not many people that relied on it.
---

Now's your chance to tell us how useful rst2man support is to you.

 INSTALL            |  7 ++----
 NEWS               |  6 +++++
 configure          | 20 +++--------------
 doc/INSTALL        | 13 -----------
 doc/Makefile.local |  7 ++----
 doc/prerst2man.py  | 64 ------------------------------------------------------
 6 files changed, 13 insertions(+), 104 deletions(-)
 delete mode 100644 doc/prerst2man.py

diff --git a/INSTALL b/INSTALL
index b543c50..eaccd93 100644
--- a/INSTALL
+++ b/INSTALL
@@ -75,14 +75,11 @@ Talloc, and zlib which are each described below:
 Building Documentation
 ----------------------
 
-By default the documentation for notmuch is built using sphinx.
+To build the documentation for notmuch you need at least version 1.0
+of sphinx (Jul. 2010).
 
 Sphinx is available from www.sphinx-doc.org.
 
-If you prefer, you can build the man pages using rst2man, from the
-python docutils package. See doc/INSTALL for details.
-
-
 Installing Dependencies from Packages
 -------------------------------------
 
diff --git a/NEWS b/NEWS
index abb5ad7..53e06aa 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,11 @@
 Notmuch 0.20 (UNRELEASED)
 
+Documentation
+-------------
+
+Support for using rst2man in place of sphinx to build the
+docmumentation has been removed.
+
 Contrib
 -------
 
diff --git a/configure b/configure
index 137acea..a6b49ae 100755
--- a/configure
+++ b/configure
@@ -447,19 +447,9 @@ printf "Checking if sphinx is available and supports nroff output... "
 if hash sphinx-build > /dev/null 2>&1 && ${python} -m sphinx.writers.manpage > /dev/null 2>&1 ; then
     printf "Yes.\n"
     have_sphinx=1
-    have_rst2man=0
 else
-    printf "No (falling back to rst2man).\n"
+    printf "No (so will not install man pages).\n"
     have_sphinx=0
-
-    printf "Checking if rst2man is available... "
-    if rst2man -V > /dev/null 2>&1; then
-       printf "Yes.\n"
-       have_rst2man=1
-    else
-       printf "No (so will not install man pages).\n"
-       have_rst2man=0
-    fi
 fi
 
 libdir_in_ldconfig=0
@@ -848,9 +838,6 @@ HAVE_EMACS = ${have_emacs}
 # Whether there's a sphinx-build binary available for building documentation
 HAVE_SPHINX=${have_sphinx}
 
-# Whether there's a rst2man binary available for building documentation
-HAVE_RST2MAN=${have_rst2man}
-
 # Whether there's a doxygen binary available for building api documentation
 HAVE_DOXYGEN=${have_doxygen}
 
@@ -978,9 +965,8 @@ cat > sh.config <<EOF
 # Whether the Xapian version in use supports compaction
 NOTMUCH_HAVE_XAPIAN_COMPACT=${have_xapian_compact}
 
-# Whether there's either sphinx or rst2man available for building
-# documentation
-NOTMUCH_HAVE_MAN=$((have_sphinx || have_rst2man))
+# do we have man pages?
+NOTMUCH_HAVE_MAN=$((have_sphinx))
 
 # Name of python interpreter
 NOTMUCH_PYTHON=${python}
diff --git a/doc/INSTALL b/doc/INSTALL
index e37c2b9..0585476 100644
--- a/doc/INSTALL
+++ b/doc/INSTALL
@@ -1,9 +1,6 @@
 This file contains some more detailed information about building and
 installing the documentation.
 
-Building with sphinx.
----------------------
-
 - You need sphinx at least version 1.0.
 
 - You can build build and install man pages with 'make install-man'
@@ -12,13 +9,3 @@ Building with sphinx.
   (currently only the man pages) with
 
      'make install-{man|info|html|pdf}'
-
-Building the man pages
-----------------------
-
-- You can build the man pages with rst2man (from python-docutils) with
-  'make rst2man'.
-
-- Currently there is no support to automagically install the resulting
-  nroff files, but it should work to modify the target install-man
-  in doc/Makefile.local.
diff --git a/doc/Makefile.local b/doc/Makefile.local
index e7d0bac..0bdf2e1 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -7,7 +7,6 @@ SPHINXOPTS    := -q
 SPHINXBUILD   = sphinx-build
 DOCBUILDDIR      := $(dir)/_build
 
-prerst2man := python $(srcdir)/$(dir)/prerst2man.py
 mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py
 
 # Internal variables.
@@ -50,8 +49,6 @@ ifeq ($(HAVE_SPHINX),1)
 	    mkdir -p $(DOCBUILDDIR)/man/man$${section}; \
 	    mv $(DOCBUILDDIR)/man/*.$${section} $(DOCBUILDDIR)/man/man$${section}; \
 	done
-else ifeq ($(HAVE_RST2MAN),1)
-	$(prerst2man) $(srcdir)/doc $(DOCBUILDDIR)/man
 else
 	@echo "Fatal: build dependency fail."
 	@false
@@ -79,10 +76,10 @@ endif
 
 # Do not try to build or install man pages if a man page converter is
 # not available.
-ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)
+ifeq ($(HAVE_SPHINX),0)
 build-man:
 install-man:
-	@echo "No sphinx or rst2man, will not install man pages."
+	@echo "No sphinx, will not install man pages."
 else
 build-man: ${MAN_GZIP_FILES}
 install-man: ${MAN_GZIP_FILES}
diff --git a/doc/prerst2man.py b/doc/prerst2man.py
deleted file mode 100644
index 968722a..0000000
--- a/doc/prerst2man.py
+++ /dev/null
@@ -1,64 +0,0 @@
-from sys import argv
-from datetime import date
-from os.path import dirname, isdir
-from os import makedirs, system
-import re
-
-sourcedir = argv[1]
-outdir = argv[2]
-
-if not isdir(outdir):
-    makedirs(outdir, 0o755)
-
-with open(sourcedir + "/conf.py") as cf:
-    exec(cf.read())
-
-
-def header(file, startdocname, command, description, authors, section):
-    file.write("""
-{0:s}
-{1:s}
-{2:s}
-
-:Date:   {3:s}
-:Version: {4:s}
-:Manual section: {5:d}
-:Manual group: {6:s}
-
-""".format(
-'-' * len(description),
-description,
-'-' * len(description),
-date.today().isoformat(), release, section, project))
-
-blankre = re.compile("^\s*$")
-for page in man_pages:
-    outdirname = outdir + '/' + dirname(page[0])
-    if not isdir(outdirname):
-        makedirs(outdirname, 0o755)
-    filename = outdir + '/' + page[0] + '.rst'
-    outfile = open(filename, 'w')
-    infile = open(sourcedir + '/' + page[0] + '.rst', 'r')
-
-    # this is a crude hack. We look for the first blank line, and
-    # insert the rst2man header there.
-    #
-    # XXX consider really parsing input
-
-    count = 0
-    lines = infile.readlines()
-    for line in lines:
-        outfile.write(line)
-        if (blankre.match(line)):
-            break
-        count = count + 1
-
-    del lines[0:count + 1]
-
-    header(outfile, *page)
-
-    outfile.write("".join(lines))
-    outfile.close()
-
-    system('set -x; rst2man {0} {1}/{2}.{3}'
-           .format(filename, outdir, page[0], page[4]))
-- 
2.1.4

Re: [PATCH] doc: remove support for rst2man

[Jani Nikula]

[-- Attachment #1: Type: text/plain, Size: 7228 bytes --]

On Jan 18, 2015 6:56 PM, "David Bremner" <david@tethera.net> wrote:
>
> It was becoming increasingly complicated to support rst2man, and there
> were apparently not many people that relied on it.
> ---
>
> Now's your chance to tell us how useful rst2man support is to you.
>
>  INSTALL            |  7 ++----
>  NEWS               |  6 +++++
>  configure          | 20 +++--------------
>  doc/INSTALL        | 13 -----------
>  doc/Makefile.local |  7 ++----
>  doc/prerst2man.py  | 64
------------------------------------------------------
>  6 files changed, 13 insertions(+), 104 deletions(-)
>  delete mode 100644 doc/prerst2man.py
>
> diff --git a/INSTALL b/INSTALL
> index b543c50..eaccd93 100644
> --- a/INSTALL
> +++ b/INSTALL
> @@ -75,14 +75,11 @@ Talloc, and zlib which are each described below:
>  Building Documentation
>  ----------------------
>
> -By default the documentation for notmuch is built using sphinx.
> +To build the documentation for notmuch you need at least version 1.0
> +of sphinx (Jul. 2010).
>
>  Sphinx is available from www.sphinx-doc.org.
>
> -If you prefer, you can build the man pages using rst2man, from the
> -python docutils package. See doc/INSTALL for details.
> -
> -
>  Installing Dependencies from Packages
>  -------------------------------------
>
> diff --git a/NEWS b/NEWS
> index abb5ad7..53e06aa 100644
> --- a/NEWS
> +++ b/NEWS
> @@ -1,5 +1,11 @@
>  Notmuch 0.20 (UNRELEASED)
>
> +Documentation
> +-------------
> +
> +Support for using rst2man in place of sphinx to build the
> +docmumentation has been removed.

-mu

Otherwise lgtm.

Jani.

> +
>  Contrib
>  -------
>
> diff --git a/configure b/configure
> index 137acea..a6b49ae 100755
> --- a/configure
> +++ b/configure
> @@ -447,19 +447,9 @@ printf "Checking if sphinx is available and supports
nroff output... "
>  if hash sphinx-build > /dev/null 2>&1 && ${python} -m
sphinx.writers.manpage > /dev/null 2>&1 ; then
>      printf "Yes.\n"
>      have_sphinx=1
> -    have_rst2man=0
>  else
> -    printf "No (falling back to rst2man).\n"
> +    printf "No (so will not install man pages).\n"
>      have_sphinx=0
> -
> -    printf "Checking if rst2man is available... "
> -    if rst2man -V > /dev/null 2>&1; then
> -       printf "Yes.\n"
> -       have_rst2man=1
> -    else
> -       printf "No (so will not install man pages).\n"
> -       have_rst2man=0
> -    fi
>  fi
>
>  libdir_in_ldconfig=0
> @@ -848,9 +838,6 @@ HAVE_EMACS = ${have_emacs}
>  # Whether there's a sphinx-build binary available for building
documentation
>  HAVE_SPHINX=${have_sphinx}
>
> -# Whether there's a rst2man binary available for building documentation
> -HAVE_RST2MAN=${have_rst2man}
> -
>  # Whether there's a doxygen binary available for building api
documentation
>  HAVE_DOXYGEN=${have_doxygen}
>
> @@ -978,9 +965,8 @@ cat > sh.config <<EOF
>  # Whether the Xapian version in use supports compaction
>  NOTMUCH_HAVE_XAPIAN_COMPACT=${have_xapian_compact}
>
> -# Whether there's either sphinx or rst2man available for building
> -# documentation
> -NOTMUCH_HAVE_MAN=$((have_sphinx || have_rst2man))
> +# do we have man pages?
> +NOTMUCH_HAVE_MAN=$((have_sphinx))
>
>  # Name of python interpreter
>  NOTMUCH_PYTHON=${python}
> diff --git a/doc/INSTALL b/doc/INSTALL
> index e37c2b9..0585476 100644
> --- a/doc/INSTALL
> +++ b/doc/INSTALL
> @@ -1,9 +1,6 @@
>  This file contains some more detailed information about building and
>  installing the documentation.
>
> -Building with sphinx.
> ----------------------
> -
>  - You need sphinx at least version 1.0.
>
>  - You can build build and install man pages with 'make install-man'
> @@ -12,13 +9,3 @@ Building with sphinx.
>    (currently only the man pages) with
>
>       'make install-{man|info|html|pdf}'
> -
> -Building the man pages
> -----------------------
> -
> -- You can build the man pages with rst2man (from python-docutils) with
> -  'make rst2man'.
> -
> -- Currently there is no support to automagically install the resulting
> -  nroff files, but it should work to modify the target install-man
> -  in doc/Makefile.local.
> diff --git a/doc/Makefile.local b/doc/Makefile.local
> index e7d0bac..0bdf2e1 100644
> --- a/doc/Makefile.local
> +++ b/doc/Makefile.local
> @@ -7,7 +7,6 @@ SPHINXOPTS    := -q
>  SPHINXBUILD   = sphinx-build
>  DOCBUILDDIR      := $(dir)/_build
>
> -prerst2man := python $(srcdir)/$(dir)/prerst2man.py
>  mkdocdeps := python $(srcdir)/$(dir)/mkdocdeps.py
>
>  # Internal variables.
> @@ -50,8 +49,6 @@ ifeq ($(HAVE_SPHINX),1)
>             mkdir -p $(DOCBUILDDIR)/man/man$${section}; \
>             mv $(DOCBUILDDIR)/man/*.$${section}
$(DOCBUILDDIR)/man/man$${section}; \
>         done
> -else ifeq ($(HAVE_RST2MAN),1)
> -       $(prerst2man) $(srcdir)/doc $(DOCBUILDDIR)/man
>  else
>         @echo "Fatal: build dependency fail."
>         @false
> @@ -79,10 +76,10 @@ endif
>
>  # Do not try to build or install man pages if a man page converter is
>  # not available.
> -ifeq ($(HAVE_SPHINX)$(HAVE_RST2MAN),00)
> +ifeq ($(HAVE_SPHINX),0)
>  build-man:
>  install-man:
> -       @echo "No sphinx or rst2man, will not install man pages."
> +       @echo "No sphinx, will not install man pages."
>  else
>  build-man: ${MAN_GZIP_FILES}
>  install-man: ${MAN_GZIP_FILES}
> diff --git a/doc/prerst2man.py b/doc/prerst2man.py
> deleted file mode 100644
> index 968722a..0000000
> --- a/doc/prerst2man.py
> +++ /dev/null
> @@ -1,64 +0,0 @@
> -from sys import argv
> -from datetime import date
> -from os.path import dirname, isdir
> -from os import makedirs, system
> -import re
> -
> -sourcedir = argv[1]
> -outdir = argv[2]
> -
> -if not isdir(outdir):
> -    makedirs(outdir, 0o755)
> -
> -with open(sourcedir + "/conf.py") as cf:
> -    exec(cf.read())
> -
> -
> -def header(file, startdocname, command, description, authors, section):
> -    file.write("""
> -{0:s}
> -{1:s}
> -{2:s}
> -
> -:Date:   {3:s}
> -:Version: {4:s}
> -:Manual section: {5:d}
> -:Manual group: {6:s}
> -
> -""".format(
> -'-' * len(description),
> -description,
> -'-' * len(description),
> -date.today().isoformat(), release, section, project))
> -
> -blankre = re.compile("^\s*$")
> -for page in man_pages:
> -    outdirname = outdir + '/' + dirname(page[0])
> -    if not isdir(outdirname):
> -        makedirs(outdirname, 0o755)
> -    filename = outdir + '/' + page[0] + '.rst'
> -    outfile = open(filename, 'w')
> -    infile = open(sourcedir + '/' + page[0] + '.rst', 'r')
> -
> -    # this is a crude hack. We look for the first blank line, and
> -    # insert the rst2man header there.
> -    #
> -    # XXX consider really parsing input
> -
> -    count = 0
> -    lines = infile.readlines()
> -    for line in lines:
> -        outfile.write(line)
> -        if (blankre.match(line)):
> -            break
> -        count = count + 1
> -
> -    del lines[0:count + 1]
> -
> -    header(outfile, *page)
> -
> -    outfile.write("".join(lines))
> -    outfile.close()
> -
> -    system('set -x; rst2man {0} {1}/{2}.{3}'
> -           .format(filename, outdir, page[0], page[4]))
> --
> 2.1.4
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch

[-- Attachment #2: Type: text/html, Size: 10001 bytes --]

Re: [PATCH] doc: remove support for rst2man

[David Bremner]

Jani Nikula <jani@nikula.org> writes:

>> +Support for using rst2man in place of sphinx to build the
>> +docmumentation has been removed.
>
> -mu
>
> Otherwise lgtm.

Fixed in git. By the way, the parent message displays very oddly for me
in emacs24; the text/plain part introduces a bunch of wrapping that
makes it look like there are many unquoted lines after this point.

notmuch-reply gets it right, so I can't show you. I'd be curious if
other people can duplicate. For a change the html version displays
perfectly.

d

Re: [PATCH] doc: remove support for rst2man

[Jani Nikula]

[-- Attachment #1: Type: text/plain, Size: 704 bytes --]

On Jan 18, 2015 10:32 PM, "David Bremner" <david@tethera.net> wrote:
>
> Jani Nikula <jani@nikula.org> writes:
>
> >> +Support for using rst2man in place of sphinx to build the
> >> +docmumentation has been removed.
> >
> > -mu
> >
> > Otherwise lgtm.
>
> Fixed in git. By the way, the parent message displays very oddly for me
> in emacs24; the text/plain part introduces a bunch of wrapping that
> makes it look like there are many unquoted lines after this point.
>
> notmuch-reply gets it right, so I can't show you. I'd be curious if
> other people can duplicate. For a change the html version displays
> perfectly.

Apologies, this is due to having to use an inferior MUA on my phone.

J.

>
> d
>

[-- Attachment #2: Type: text/html, Size: 1045 bytes --]

Re: [PATCH] doc: remove support for rst2man

[David Bremner]

Jani Nikula <jani@nikula.org> writes:

>
> Apologies, this is due to having to use an inferior MUA on my phone.
>

Ah, it really is wrapped in the raw version. My mistake, I thought
something interesting was going on, not just the usual bad MUA software
;).

d

Re: [PATCH] doc: remove support for rst2man

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 198 bytes --]

Looks good to me :).

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH] doc: remove support for rst2man

[David Bremner]

David Bremner <david@tethera.net> writes:

> It was becoming increasingly complicated to support rst2man, and there
> were apparently not many people that relied on it.
> ---
>
> Now's your chance to tell us how useful rst2man support is to you.

Nobody complained, so I merged this change.

d