[PATCH] doc: build man pages at build time, not install

[PATCH] doc: build man pages at build time, not install

[David Bremner]

This helps avoid build artifacts (namely, nroff and gzipped-nroff man
pages) owned by root.
---
 Makefile.local     | 2 +-
 doc/Makefile.local | 6 ++++--
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Makefile.local b/Makefile.local
index 5f797ad..cb7b106 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -53,7 +53,7 @@ endif
 FINAL_LIBNOTMUCH_LDFLAGS = $(LDFLAGS) $(AS_NEEDED_LDFLAGS) $(CONFIGURE_LDFLAGS)
 
 .PHONY: all
-all: notmuch notmuch-shared
+all: notmuch notmuch-shared build-man
 ifeq ($(MAKECMDGOALS),)
 ifeq ($(shell cat .first-build-message 2>/dev/null),)
 	@NOTMUCH_FIRST_BUILD=1 $(MAKE) --no-print-directory all
diff --git a/doc/Makefile.local b/doc/Makefile.local
index fd64f70..5be49dc 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -16,7 +16,7 @@ ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
 .PHONY: sphinx-html sphinx-man sphinx-texinfo sphinx-info
 .PHONY: rst2man
 
-.PHONY: install-man
+.PHONY: install-man build-man
 
 %.gz: %
 	rm -f $@ && gzip --stdout $^ > $@
@@ -43,7 +43,9 @@ MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
 
 ${MAN_ROFF_FILES} : sphinx-man
 
-install-man: ${MAN_GZIP_FILES}
+build-man: ${MAN_GZIP_FILES}
+
+install-man: build-man
 	mkdir -p "$(DESTDIR)$(mandir)/man1"
 	mkdir -p "$(DESTDIR)$(mandir)/man5"
 	mkdir -p "$(DESTDIR)$(mandir)/man7"
-- 
1.8.5.3

Re: [PATCH] doc: build man pages at build time, not install

[Tomi Ollila]

On Mon, Mar 10 2014, David Bremner <david@tethera.net> wrote:

> This helps avoid build artifacts (namely, nroff and gzipped-nroff man
> pages) owned by root.
> ---

Looks good... on paper :D. +1

Tomi

>  Makefile.local     | 2 +-
>  doc/Makefile.local | 6 ++++--
>  2 files changed, 5 insertions(+), 3 deletions(-)
>
> diff --git a/Makefile.local b/Makefile.local
> index 5f797ad..cb7b106 100644
> --- a/Makefile.local
> +++ b/Makefile.local
> @@ -53,7 +53,7 @@ endif
>  FINAL_LIBNOTMUCH_LDFLAGS = $(LDFLAGS) $(AS_NEEDED_LDFLAGS) $(CONFIGURE_LDFLAGS)
>  
>  .PHONY: all
> -all: notmuch notmuch-shared
> +all: notmuch notmuch-shared build-man
>  ifeq ($(MAKECMDGOALS),)
>  ifeq ($(shell cat .first-build-message 2>/dev/null),)
>  	@NOTMUCH_FIRST_BUILD=1 $(MAKE) --no-print-directory all
> diff --git a/doc/Makefile.local b/doc/Makefile.local
> index fd64f70..5be49dc 100644
> --- a/doc/Makefile.local
> +++ b/doc/Makefile.local
> @@ -16,7 +16,7 @@ ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
>  .PHONY: sphinx-html sphinx-man sphinx-texinfo sphinx-info
>  .PHONY: rst2man
>  
> -.PHONY: install-man
> +.PHONY: install-man build-man
>  
>  %.gz: %
>  	rm -f $@ && gzip --stdout $^ > $@
> @@ -43,7 +43,9 @@ MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
>  
>  ${MAN_ROFF_FILES} : sphinx-man
>  
> -install-man: ${MAN_GZIP_FILES}
> +build-man: ${MAN_GZIP_FILES}
> +
> +install-man: build-man
>  	mkdir -p "$(DESTDIR)$(mandir)/man1"
>  	mkdir -p "$(DESTDIR)$(mandir)/man5"
>  	mkdir -p "$(DESTDIR)$(mandir)/man7"
> -- 
> 1.8.5.3
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH] doc: build man pages at build time, not install

[Jani Nikula]

On Mon, 10 Mar 2014, David Bremner <david@tethera.net> wrote:
> This helps avoid build artifacts (namely, nroff and gzipped-nroff man
> pages) owned by root.
> ---
>  Makefile.local     | 2 +-
>  doc/Makefile.local | 6 ++++--
>  2 files changed, 5 insertions(+), 3 deletions(-)
>
> diff --git a/Makefile.local b/Makefile.local
> index 5f797ad..cb7b106 100644
> --- a/Makefile.local
> +++ b/Makefile.local
> @@ -53,7 +53,7 @@ endif
>  FINAL_LIBNOTMUCH_LDFLAGS = $(LDFLAGS) $(AS_NEEDED_LDFLAGS) $(CONFIGURE_LDFLAGS)
>  
>  .PHONY: all
> -all: notmuch notmuch-shared
> +all: notmuch notmuch-shared build-man
>  ifeq ($(MAKECMDGOALS),)
>  ifeq ($(shell cat .first-build-message 2>/dev/null),)
>  	@NOTMUCH_FIRST_BUILD=1 $(MAKE) --no-print-directory all
> diff --git a/doc/Makefile.local b/doc/Makefile.local
> index fd64f70..5be49dc 100644
> --- a/doc/Makefile.local
> +++ b/doc/Makefile.local
> @@ -16,7 +16,7 @@ ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
>  .PHONY: sphinx-html sphinx-man sphinx-texinfo sphinx-info
>  .PHONY: rst2man
>  
> -.PHONY: install-man
> +.PHONY: install-man build-man
>  
>  %.gz: %
>  	rm -f $@ && gzip --stdout $^ > $@
> @@ -43,7 +43,9 @@ MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
>  
>  ${MAN_ROFF_FILES} : sphinx-man
>  
> -install-man: ${MAN_GZIP_FILES}
> +build-man: ${MAN_GZIP_FILES}
> +
> +install-man: build-man

Because build-man is a .PHONY target, it'll get done also on
install-man, and one still ends up with root owned files on 'sudo make
install'. The improvement to previous is that doc/_build/man directory
is now created in the build phase and the files can be removed by the
regular user.

An actual non-phony dependency chain from .gz to man page to rst would
be awesome, but I don't know how hard it would be with the
sphinx/rst2man targets.

BR,
Jani.


>  	mkdir -p "$(DESTDIR)$(mandir)/man1"
>  	mkdir -p "$(DESTDIR)$(mandir)/man5"
>  	mkdir -p "$(DESTDIR)$(mandir)/man7"
> -- 
> 1.8.5.3
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch

Re: [PATCH] doc: build man pages at build time, not install

[Tomi Ollila]

On Mon, Mar 10 2014, Jani Nikula <jani@nikula.org> wrote:

>
> Because build-man is a .PHONY target, it'll get done also on
> install-man, and one still ends up with root owned files on 'sudo make
> install'. The improvement to previous is that doc/_build/man directory
> is now created in the build phase and the files can be removed by the
> regular user.
>
> An actual non-phony dependency chain from .gz to man page to rst would
> be awesome, but I don't know how hard it would be with the
> sphinx/rst2man targets.

instead of having the targets as .PHONY those should depend on all source
files...

... perhaps better alternative is to have those still as .PHONY so those
can be neat make targets, but greate new *.stamp targets that depend on
the source files (and these *.stamp targets have the recipes)

(actually, after I added the stuff below, sphinx-man doesn't need to be
PHONY anymore).

something like:

sphinx-man: $(DOCBUILDDIR)/man.stamp

$(DOCBUILDDIR)/man.stamp: $(MAN_SRC_FILES)
ifeq($(HAVE_SPHINX), 1)
          $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
          touch $@
else
ifeq($(HAVE_RST2HTML), 1)
          $(prerst2man) $(DOCBUILDDIR)/.. $(DOCBUILDDIR)/man
          touch $@
endif
endif


mkdocdeps.py could create $(MAN_SRC_FILES) and friends pretty easily.

(sphinx-man could be changed to just 'man', and if anyone wanted to
make manual pages from command line using rst2man that could
work as `make man HAVE_SPHINX=0 HAVE_RST2HTML=1')


> BR,
> Jani.


Tomi

[PATCH 1/3] doc: build man pages at build time; introduce HAVE_SPHINX, HAVE_RST2MAN

[David Bremner]

This helps avoid build artifacts (namely, nroff and gzipped-nroff man
pages) owned by root.

The variables allow choosing which generator to use for the man page.
These will be hooked to configure in a following commit.
---
 Makefile.local     |  2 +-
 doc/Makefile.local | 31 ++++++++++++++++++-------------
 doc/mkdocdeps.py   |  3 +++
 3 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/Makefile.local b/Makefile.local
index 5f797ad..cb7b106 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -53,7 +53,7 @@ endif
 FINAL_LIBNOTMUCH_LDFLAGS = $(LDFLAGS) $(AS_NEEDED_LDFLAGS) $(CONFIGURE_LDFLAGS)
 
 .PHONY: all
-all: notmuch notmuch-shared
+all: notmuch notmuch-shared build-man
 ifeq ($(MAKECMDGOALS),)
 ifeq ($(shell cat .first-build-message 2>/dev/null),)
 	@NOTMUCH_FIRST_BUILD=1 $(MAKE) --no-print-directory all
diff --git a/doc/Makefile.local b/doc/Makefile.local
index fd64f70..23f4095 100644
--- a/doc/Makefile.local
+++ b/doc/Makefile.local
@@ -13,10 +13,9 @@ mkdocdeps := python $(dir)/mkdocdeps.py
 # Internal variables.
 ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
 
-.PHONY: sphinx-html sphinx-man sphinx-texinfo sphinx-info
-.PHONY: rst2man
+.PHONY: sphinx-html sphinx-texinfo sphinx-info
 
-.PHONY: install-man
+.PHONY: install-man build-man
 
 %.gz: %
 	rm -f $@ && gzip --stdout $^ > $@
@@ -24,24 +23,30 @@ ALLSPHINXOPTS   := -d $(DOCBUILDDIR)/doctrees $(SPHINXOPTS) $(dir)
 sphinx-html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(DOCBUILDDIR)/html
 
-sphinx-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
-
 sphinx-texinfo:
 	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(DOCBUILDDIR)/texinfo
 
 sphinx-info: sphinx-texinfo
 	make -C $(DOCBUILDDIR)/texinfo info
 
-# fallback target in case sphinx not installed
-rst2man:
-	$(prerst2man) $(DOCBUILDDIR)/.. $(DOCBUILDDIR)/man
-
 -include $(dir)/docdeps.mk
 
 MAN_GZIP_FILES := $(addsuffix .gz,${MAN_ROFF_FILES})
 
-${MAN_ROFF_FILES} : sphinx-man
+build-man: ${MAN_GZIP_FILES}
+
+${MAN_ROFF_FILES}: ${dir}/man.stamp
+
+$(dir)/man.stamp: ${MAN_RST_FILES}
+ifeq ($(HAVE_SPHINX),1)
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(DOCBUILDDIR)/man
+	touch $@
+else ifeq ($(HAVE_RST2MAN),1)
+	$(prerst2man) $(DOCBUILDDIR)/.. $(DOCBUILDDIR)/man
+	touch $@
+else
+	@echo "No sphinx or rst2man, will not install man pages."
+endif
 
 install-man: ${MAN_GZIP_FILES}
 	mkdir -p "$(DESTDIR)$(mandir)/man1"
@@ -52,8 +57,8 @@ install-man: ${MAN_GZIP_FILES}
 	install -m0644 $(DOCBUILDDIR)/man/*.7.gz $(DESTDIR)/$(mandir)/man7
 	cd $(DESTDIR)/$(mandir)/man1 && ln -sf notmuch.1.gz notmuch-setup.1.gz
 
-
 $(dir)/docdeps.mk: $(dir)/conf.py $(dir)/mkdocdeps.py
 	$(mkdocdeps) $< $(DOCBUILDDIR) $@
 
-CLEAN := $(CLEAN) $(DOCBUILDDIR) $(dir)/docdeps.mk
+CLEAN := $(CLEAN) $(DOCBUILDDIR) $(dir)/docdeps.mk $(dir)/man.stamp
+CLEAN := $(CLEAN) $(MAN_GZIP_FILES) $(MAN_ROFF_FILES)
diff --git a/doc/mkdocdeps.py b/doc/mkdocdeps.py
index 2f4a959..e61bea6 100644
--- a/doc/mkdocdeps.py
+++ b/doc/mkdocdeps.py
@@ -6,8 +6,11 @@ outfile = argv[3]
 execfile(conffile)
 
 roff_files = []
+rst_files = []
 out=open(outfile,'w')
 for page in man_pages:
+    rst_files = rst_files + ["doc/{0:s}.rst".format(page[0])]
     roff_files = roff_files + ["{0:s}/man/{1:s}.{2:d}".format(builddir,page[1],page[4])]
 
 out.write ('MAN_ROFF_FILES := ' + ' \\\n\t'.join(roff_files)+'\n')
+out.write ('MAN_RST_FILES := ' + ' \\\n\t'.join(rst_files)+'\n')
-- 
1.8.5.3

[PATCH 2/3] doc: configure detection of sphinx and rst2man

[David Bremner]

Because sphinx-build does not provide a convenient way of listing
which builders exist, and some people actually have pre 1.0 sphinx, we
try loading a relevant python module.

Currently the assumption is that no python in path -> no sphinx-build
in path.
---
 configure | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/configure b/configure
index 2eaed4a..10356e7 100755
--- a/configure
+++ b/configure
@@ -393,6 +393,27 @@ else
     have_emacs=0
 fi
 
+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"
+    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
 
 printf "Checking which platform we are on... "
@@ -759,6 +780,12 @@ emacsetcdir=${EMACSETCDIR}
 # Whether there's an emacs binary available for byte-compiling
 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 and used for building documentation
+HAVE_RST2MAN=${have_rst2man}
+
 # The directory to which desktop files should be installed
 desktop_dir = \$(prefix)/share/applications
 
-- 
1.8.5.3

[PATCH 3/3] doc: have prerst2man.py generate roff files all in one directory

[David Bremner]

Originally it seemed tidier to put them in subdirectories, but it
turned out not to be obvious how to do that with sphinx. Bring the two
methods back in sync again, and unbreak the generation of gzipped
manpages.

As a side-effect, fix a particular egregious combination of format and
string concatenation.
---
 doc/prerst2man.py | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/doc/prerst2man.py b/doc/prerst2man.py
index 720deb6..adc0d3d 100644
--- a/doc/prerst2man.py
+++ b/doc/prerst2man.py
@@ -32,10 +32,8 @@ 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, 0755)
-    filename = outdir + '/' + page[0] + '.rst'
+    print outdir
+    filename = outdir + '/' + page[1] + '.rst'
     outfile = open(filename, 'w')
     infile = open(sourcedir + '/' + page[0] + '.rst', 'r')
 
@@ -59,4 +57,5 @@ for page in man_pages:
     outfile.write("".join(lines))
     outfile.close()
 
-    os.system('set -x; rst2man {0} {1}'.format(filename, outdir + '/' + page[0] + '.' + str(page[4])))
+    os.system('set -x; rst2man {0} {1}/{2}.{3}'
+              .format(filename, outdir, page[1],page[4]))
-- 
1.8.5.3

Re: [PATCH 3/3] doc: have prerst2man.py generate roff files all in one directory

[David Bremner]

David Bremner <david@tethera.net> writes:

> +    print outdir

gah, debugging print. fixed in git