From: Iustin Pop Date: Tue, 7 Apr 2009 11:53:58 +0000 (+0000) Subject: Distribute built documentation X-Git-Tag: v2.0.0rc3~1 X-Git-Url: https://code.grnet.gr/git/ganeti-local/commitdiff_plain/2ab2b9f53677e48594773ba0470002d664f6f35c 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 --- 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 --- 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 --- 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