Commit 2ab2b9f5 authored by Iustin Pop's avatar Iustin Pop

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
parent 77921a95
......@@ -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/
......
......@@ -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
......
......@@ -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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment