From c7f75bf04d07506bd4d9e862b9b38a1e423d88b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= <berrange@redhat.com>
Date: Fri, 18 Oct 2019 14:18:36 +0100
Subject: [PATCH] docs: introduce rst2html as a mandatory tool for building
 docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 .travis.yml                  |  1 +
 docs/Makefile.am             | 33 +++++++++++++++++++++++++++------
 libvirt.spec.in              |  2 ++
 m4/virt-external-programs.m4 |  5 +++++
 mingw-libvirt.spec.in        |  1 +
 5 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 80f3be5490..b47f54553e 100644
--- 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 49270f0bdf..5f5dce28eb 100644
--- 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 72ed2fd96b..c431f0dfb5 100644
--- 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 0f995998c3..ed634a4c73 100644
--- 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 fd9b729591..033c8f9658 100644
--- 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