Distribute built documentation

This patch changes the way documentation is built in order to distribute
the generated output in the 'dist' archive, and thus no longer
requiring the presence of the docbook/rst toolchains during build time.
This will lower the requirements for installation and also makes the
build time insignificant.

First, we remove the docbook2pdf rules and variables, since we no longer
build this kind of docs. Furthermore, the rst source files are not
(today) processed via replace_vars_sed, so the whole .in rules for doc/
go away.

Next, we change the ".sgml|.rst -> replace_vars_sed -> .in -> processor
-> final file" processing to ".sgml|.rst -> generator -> .in ->
replace_vars_sed -> final file"; this means we first process the file
using the formatter, with the @VARIABLE@ entries in it, and save the
output as .in; this output we distribute, and on the user side, the
replace_vars_sed will use the new configure flags to transform the
(almost final .in form) to the final form, without needing the
toolchain.

In configure.ac we also change from ERROR to WARN for the documentation
generators, and extra tests in Makefile.am check that the programs have
been found.

This was tested with distcheck and works as expected.

Reviewed-by: ultrotter

diff --git a/DEVNOTES b/DEVNOTES
index 414c974..b4146c4 100644 (file)
--- a/DEVNOTES
+++ b/DEVNOTES
@@ -5,7 +5,7 @@ Build dependencies
 ------------------
 
 Most dependencies from INSTALL, plus:
- - docbook2html, docbook2man, docbook2pdf from Docbook tools
+ - docbook2html, docbook2man from Docbook tools
    http://sources.redhat.com/docbook-tools/
  - rst2html from Docutils
    http://docutils.sourceforge.net/

diff --git a/Makefile.am b/Makefile.am
index 7206b09..2d99c1c 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -37,13 +37,14 @@ DIRS = \
        test/data \
        tools
 
+MAINTAINERCLEANFILES = \
+       $(dochtml) \
+       $(patsubst %.dot,%.png,$(docdot)) \
+       $(maninput)
+
 CLEANFILES = \
        autotools/replace_vars.sed \
        devel/upload \
-       doc/*.html \
-       doc/*.in \
-       doc/*.pdf \
-       $(patsubst %.dot,%.png,$(docdot)) \
        doc/rapi-resources.gen \
        doc/examples/bash_completion \
        doc/examples/ganeti.initd \
@@ -52,9 +53,8 @@ CLEANFILES = \
        lib/http/*.py[co] \
        lib/hypervisor/*.py[co] \
        lib/rapi/*.py[co] \
-       man/*.[78] \
-       man/*.in \
-       man/*.html \
+       $(man_MANS) \
+       $(manhtml) \
        qa/*.py[co] \
        test/*.py[co] \
        stamp-directories \
@@ -116,11 +116,12 @@ docrst = \
        doc/install.rst \
        doc/security.rst
 
+dochtml = $(patsubst %.rst,%.html,$(docrst))
+
 docdot = \
        doc/arch-2.0.dot
 
-doc_DATA = \
-       $(patsubst %.rst,%.html,$(docrst))
+doc_DATA = $(dochtml)
 
 noinst_DATA = $(manhtml)
 
@@ -144,6 +145,7 @@ dist_tools_SCRIPTS = \
        tools/lvmstrap
 
 EXTRA_DIST = \
+       $(MAINTAINERCLEANFILES) \
        NEWS \
        DEVNOTES \
        autotools/docbook-wrapper \
@@ -161,7 +163,7 @@ EXTRA_DIST = \
        $(dist_TESTS) \
        $(TEST_FILES) \
        man/footer.sgml \
-       $(mansgml) \
+       $(mansgml) $(maninput) \
        qa/ganeti-qa.py \
        qa/qa-sample.json \
        qa/qa_cluster.py \
@@ -191,9 +193,9 @@ man_MANS = \
        man/gnt-node.8 \
        man/gnt-os.8
 
-maninput = $(patsubst %.7,%.in,$(patsubst %.8,%.in,$(man_MANS)))
-mansgml = $(patsubst %.in,%.sgml,$(maninput))
-manhtml = $(patsubst %.in,%.html,$(maninput))
+mansgml = $(patsubst %.7,%.sgml,$(patsubst %.8,%.sgml,$(man_MANS)))
+manhtml = $(patsubst %.sgml,%.html,$(mansgml))
+maninput = $(patsubst %.7,%.7.in,$(patsubst %.8,%.8.in,$(man_MANS))) $(patsubst %.html,%.html.in,$(manhtml))
 
 TEST_FILES = \
        test/data/bdev-both.txt \
@@ -236,37 +238,46 @@ doc/examples/%: doc/examples/%.in stamp-directories \
                $(REPLACE_VARS_SED)
        sed -f $(REPLACE_VARS_SED) < $< > $@
 
-doc/%.in: doc/%.sgml stamp-directories $(REPLACE_VARS_SED)
-       sed -f $(REPLACE_VARS_SED) < $< > $@
-
-man/%.in: man/%.sgml stamp-directories $(REPLACE_VARS_SED)
-       sed -f $(REPLACE_VARS_SED) < $< > $@
-
-doc/%.pdf: doc/%.in $(DOCBOOK_WRAPPER)
-       $(DOCBOOK_WRAPPER) "$(DOCBOOK2PDF)" $< $@
-
 doc/%.html: doc/%.rst
+       @test -n "$(RST2HTML)" || { echo 'rst2html' not found during configure; exit 1; }
        $(RST2HTML) $< $@
 
 doc/%.png: doc/%.dot
+       @test -n "$(DOT)" || { echo 'dot' not found during configure; exit 1; }
        $(DOT) -Tpng -o $@ $<
 
 doc/design-2.0.html: doc/design-2.0.rst doc/arch-2.0.png
 
-doc/rapi.pdf doc/rapi.html: doc/rapi-resources.gen
+doc/rapi.html: doc/rapi-resources.gen
 
 doc/rapi-resources.gen: $(BUILD_RAPI_RESOURCE_DOC) $(RAPI_RESOURCES)
        PYTHONPATH=.:$(top_builddir) $(BUILD_RAPI_RESOURCE_DOC) > $@ || \
          rm -f $@
 
-man/%.7: man/%.in man/footer.sgml $(DOCBOOK_WRAPPER)
-       $(DOCBOOK_WRAPPER) "$(DOCBOOK2MAN)" $< $@
+man/%.7.in man/%.8.in: man/%.sgml man/footer.sgml $(DOCBOOK_WRAPPER)
+       @test -n "$(DOCBOOK2MAN)" || { echo 'doocbook2html' not found during configure; exit 1; }
+       TMPDIR=`mktemp -d` && { \
+       $(DOCBOOK_WRAPPER) "$(DOCBOOK2MAN)" $< $$TMPDIR/$(patsubst man/%.in,%,$@) ; \
+       mv $$TMPDIR/$(patsubst man/%.in,%,$@) $@ ; \
+       rm -rf "$$TMPDIR" ; \
+       }
+
+man/%.html.in: man/%.sgml man/footer.sgml $(DOCBOOK_WRAPPER)
+       @test -n "$(DOCBOOK2HTML)" || { echo 'doocbook2html' not found during configure; exit 1; }
+       TMPDIR=`mktemp -d` && { \
+       $(DOCBOOK_WRAPPER) "$(DOCBOOK2HTML) --nochunks" $< $$TMPDIR/$(patsubst man/%.in,%,$@) ; \
+       mv $$TMPDIR/$(patsubst man/%.in,%,$@) $@ ; \
+       rm -rf "$$TMPDIR" ; \
+       }
+
+man/%.7: man/%.7.in stamp-directories $(REPLACE_VARS_SED)
+       sed -f $(REPLACE_VARS_SED) < $< > $@
 
-man/%.8: man/%.in man/footer.sgml $(DOCBOOK_WRAPPER)
-       $(DOCBOOK_WRAPPER) "$(DOCBOOK2MAN)" $< $@
+man/%.8: man/%.8.in stamp-directories $(REPLACE_VARS_SED)
+       sed -f $(REPLACE_VARS_SED) < $< > $@
 
-man/%.html: man/%.in $(DOCBOOK_WRAPPER)
-       $(DOCBOOK_WRAPPER) "$(DOCBOOK2HTML) --nochunks" $< $@
+man/%.html: man/%.html.in stamp-directories $(REPLACE_VARS_SED)
+       sed -f $(REPLACE_VARS_SED) < $< > $@
 
 man/footer.sgml $(TESTS): srclinks
 

diff --git a/configure.ac b/configure.ac
index 260e429..d8a6b84 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -128,21 +128,14 @@ AC_ARG_VAR(DOCBOOK2MAN, [docbook2man path])
 AC_PATH_PROG(DOCBOOK2MAN, [docbook2man], [])
 if test -z "$DOCBOOK2MAN"
 then
-  AC_MSG_ERROR([docbook2man not found])
-fi
-
-AC_ARG_VAR(DOCBOOK2PDF, [docbook2pdf path])
-AC_PATH_PROG(DOCBOOK2PDF, [docbook2pdf], [])
-if test -z "$DOCBOOK2PDF"
-then
-  AC_MSG_ERROR([docbook2pdf not found])
+  AC_MSG_WARN([docbook2man not found, man pages rebuild will not be possible])
 fi
 
 AC_ARG_VAR(DOCBOOK2HTML, [docbook2html path])
 AC_PATH_PROG(DOCBOOK2HTML, [docbook2html], [])
 if test -z "$DOCBOOK2HTML"
 then
-  AC_MSG_ERROR([docbook2html not found])
+  AC_MSG_WARN([docbook2html not found, man pages rebuild will not be possible])
 fi
 
 # Check for rst programs
@@ -150,7 +143,7 @@ AC_ARG_VAR(RST2HTML, [rst2html path])
 AC_PATH_PROG(RST2HTML, [rst2html], [])
 if test -z "$RST2HTML"
 then
-  AC_MSG_ERROR([rst2html not found])
+  AC_MSG_WARN([rst2html not found, documentation rebuild will not be possible])
 fi
 
 # Check for graphviz (dot)
@@ -158,7 +151,7 @@ AC_ARG_VAR(DOT, [dot path])
 AC_PATH_PROG(DOT, [dot], [])
 if test -z "$DOT"
 then
-  AC_MSG_ERROR([dot (from the graphviz suite) not found])
+  AC_MSG_WARN([dot (from the graphviz suite) not found, documentation rebuild not possible])
 fi
 
 # Check for Python