[libvirt] [PATCH v2 03/15] 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.
Signed-off-by: Daniel P. Berrangé <berrange(a)redhat.com>
---
docs/Makefile.am | 33 +++++++++++++++++++++++++++------
libvirt.spec.in | 2 ++
m4/virt-external-programs.m4 | 5 +++++
mingw-libvirt.spec.in | 1 +
4 files changed, 35 insertions(+), 6 deletions(-)
diff --git a/docs/Makefile.am b/docs/Makefile.am
index 2a104bc837..7a8adbde2b 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= \
apibuild.py 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 a6219da604..5c47dd3d7c 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 c29f3eeed2..35f1abc13d 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
--
2.23.0