docs: introduce rst2html as a mandatory tool for building docs

The rst2html tool is provided by python docutils, and as the name
suggests, it converts RST documents into HTML.

Basic rules are added for integrating RST docs into the website
build process.

This enables us to start writing docs on our website in RST format
instead of HTML, without changing the rest of our website templating
system away from XSLT yet.

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>

diff --git a/.travis.yml b/.travis.yml
index 80f3be54906725bc10f8f9b84aeeb9af7d440eab..b47f54553eb44f62ceb3aab394ec2b577b136f47 100644 (file)
--- a/.travis.yml
+++ b/.travis.yml
@@ -14,6 +14,7 @@ addons:
       - xz
       - yajl
       - glib
+      - docutils
 
 matrix:
   include:

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 49270f0bdf89c7f0a19be7ec66a2b9595cf691c3..5f5dce28eb3e7f35259606d6335f0d55c3bfbc0e 100644 (file)
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -173,14 +173,26 @@ gif = \
 
 internals_html_in = \
   $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/internals/*.html.in))
-internals_html = $(internals_html_in:%.html.in=%.html)
+kbase_rst = \
+  $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/kbase/*.rst))
+kbase_rst_html_in = \
+  $(kbase_rst:%.rst=%.html.in)
+internals_html = \
+  $(internals_html_in:%.html.in=%.html) \
+  $(internals_rst_html_in:%.html.in=%.html)
 
 internalsdir = $(HTML_DIR)/internals
 internals_DATA = $(internals_html)
 
 kbase_html_in = \
   $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/kbase/*.html.in))
-kbase_html = $(kbase_html_in:%.html.in=%.html)
+kbase_rst = \
+  $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/kbase/*.rst))
+kbase_rst_html_in = \
+  $(kbase_rst:%.rst=%.html.in)
+kbase_html = \
+  $(kbase_html_in:%.html.in=%.html) \
+  $(kbase_rst_html_in:%.html.in=%.html)
 
 kbasedir = $(HTML_DIR)/kbase
 kbase_DATA = $(kbase_html)
@@ -191,9 +203,14 @@ dot_html_generated_in = \
   news.html.in
 dot_html_in = \
   $(notdir $(wildcard $(srcdir)/*.html.in))
+dot_rst = \
+  $(notdir $(wildcard $(srcdir)/*.rst))
+dot_rst_html_in = \
+  $(dot_rst:%.rst=%.html)
 dot_html = \
   $(dot_html_generated_in:%.html.in=%.html) \
-  $(dot_html_in:%.html.in=%.html)
+  $(dot_html_in:%.html.in=%.html) \
+  $(dot_rst_html_in:%.html.in=%.html)
 
 htmldir = $(HTML_DIR)
 html_DATA = $(css) $(png) $(gif) $(dot_html)
@@ -222,11 +239,11 @@ EXTRA_DIST= \
   genaclperms.pl \
   site.xsl subsite.xsl newapi.xsl page.xsl \
   wrapstring.xsl \
-  $(dot_html_in) $(gif) $(apipng) \
+  $(dot_html_in) $(dot_rst) $(gif) $(apipng) \
   $(fig) $(png) $(css) \
   $(javascript) $(logofiles) \
-  $(internals_html_in) $(fonts) \
-  $(kbase_html_in) \
+  $(internals_html_in) $(internals_rst) $(fonts) \
+  $(kbase_html_in) $(kbase_rst) \
   aclperms.htmlinc \
   hvsupport.pl \
   $(schema_DATA)
@@ -281,6 +298,10 @@ EXTRA_DIST += \
 %.png: %.fig
        convert -rotate 90 $< $@
 
+%.html.in: %.rst
+       $(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
+         $(RST2HTML) $< > $@
+
 %.html.tmp: %.html.in site.xsl subsite.xsl page.xsl \
                $(acl_generated)
        $(AM_V_GEN)name=`echo $@ | sed -e 's/.tmp//'`; \

diff --git a/libvirt.spec.in b/libvirt.spec.in
index 72ed2fd96bb190c5e3b7442386fc35220fcc1cc0..c431f0dfb5fc44c0898e72e2936c11adf64e8736 100644 (file)
--- a/libvirt.spec.in
+++ b/libvirt.spec.in
@@ -265,6 +265,8 @@ BuildRequires: automake
 BuildRequires: gettext-devel
 BuildRequires: libtool
 BuildRequires: /usr/bin/pod2man
+# Replace with python3-docutils when we drop py2 support
+BuildRequires: /usr/bin/rst2html
 %endif
 BuildRequires: gcc
 BuildRequires: git

diff --git a/m4/virt-external-programs.m4 b/m4/virt-external-programs.m4
index 0f995998c3b64d8e9dfa78b6fd118c46a3195ad5..ed634a4c734b59cb022f25659f1ff1b157ab9816 100644 (file)
--- a/m4/virt-external-programs.m4
+++ b/m4/virt-external-programs.m4
@@ -33,6 +33,11 @@ AC_DEFUN([LIBVIRT_CHECK_EXTERNAL_PROGRAMS], [
   then
     AC_MSG_ERROR("xsltproc is required to build libvirt")
   fi
+  AC_PATH_PROGS([RST2HTML], [rst2html rst2html.py rst2html-3], [])
+  if test -z "$RST2HTML"
+  then
+    AC_MSG_ERROR("rst2html is required to build libvirt")
+  fi
   AC_PATH_PROG([AUGPARSE], [augparse], [/usr/bin/augparse])
   AC_PROG_MKDIR_P
   AC_PROG_LN_S

diff --git a/mingw-libvirt.spec.in b/mingw-libvirt.spec.in
index fd9b7295914091eed421b418fd0e7f9462a763ef..033c8f96589da1d18979b62e136d1ca77061ec7c 100644 (file)
--- a/mingw-libvirt.spec.in
+++ b/mingw-libvirt.spec.in
@@ -82,6 +82,7 @@ BuildRequires: automake
 BuildRequires: gettext-devel
 BuildRequires: libtool
 %endif
+BuildRequires: python3-docutils
 
 BuildRequires: mingw32-libssh2
 BuildRequires: mingw64-libssh2