[libvirt] [PATCH 04/17] docs: introduce rst2man as a mandatory tool for building docs

[Daniel P. Berrangé]

The rst2man tool is provided by python docutils, and as the name
suggests, it converts RST documents into man pages.

The intention is that our current POD docs will be converted to
RST format, allowing one more use of Perl to be eliminated from
libvirt.

The manual pages will now all be kept in the docs/manpages/ directory,
which enables us to include the man pages in the published website.
This is good for people searching for libvirt man pages online as it
makes it more likely google will send them to the libvirt.org instead
of some random third party man page site with outdated content.

Signed-off-by: Daniel P. Berrangé <berrange at redhat.com>
---
 docs/Makefile.am             | 60 ++++++++++++++++++++++++++++++++++++
 docs/docs.html.in            |  3 ++
 docs/manpages/index.rst      |  3 ++
 m4/virt-external-programs.m4 |  5 +++
 4 files changed, 71 insertions(+)
 create mode 100644 docs/manpages/index.rst

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 5f5dce28eb..34fea87805 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -197,6 +197,54 @@ kbase_html = \
 kbasedir = $(HTML_DIR)/kbase
 kbase_DATA = $(kbase_html)
 
+manpages_rst = \
+  manpages/index.rst \
+  $(NULL)
+manpages1_rst = \
+  $(NULL)
+manpages7_rst = \
+  $(NULL)
+manpages8_rst = \
+  $(NULL)
+manpages_rst += \
+  $(manpages1_rst) \
+  $(manpages7_rst) \
+  $(manpages8_rst) \
+  $(NULL)
+manpages_rst_html_in = \
+  $(manpages_rst:%.rst=%.html.in)
+manpages_html = \
+  $(manpages_rst_html_in:%.html.in=%.html)
+
+man1_MANS = $(manpages1_rst:%.rst=%.1)
+man7_MANS = $(manpages7_rst:%.rst=%.7)
+man8_MANS = $(manpages8_rst:%.rst=%.8)
+
+%.1: %.rst
+	$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
+	   grep -v '^\.\. contents::' < $< | \
+	   sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \
+	       -e 's|RUNSTATEDIR|$(runstatedir)|g' | \
+	   $(RST2MAN) > $@
+
+%.7: %.rst
+	$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
+	   grep -v '^\.\. contents::' < $< | \
+	   sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \
+	       -e 's|RUNSTATEDIR|$(runstatedir)|g' | \
+	   $(RST2MAN) > $@
+
+%.8: %.rst
+	$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
+	   grep -v '^\.\. contents::' < $< | \
+	   sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \
+	       -e 's|RUNSTATEDIR|$(runstatedir)|g' | \
+	   $(RST2MAN) > $@
+
+
+manpagesdir = $(HTML_DIR)/manpages
+manpages_DATA = $(manpages_html)
+
 # Generate hvsupport.html and news.html first, since they take one extra step.
 dot_html_generated_in = \
   hvsupport.html.in \
@@ -244,6 +292,7 @@ EXTRA_DIST= \
   $(javascript) $(logofiles) \
   $(internals_html_in) $(internals_rst) $(fonts) \
   $(kbase_html_in) $(kbase_rst) \
+  $(manpages_rst) \
   aclperms.htmlinc \
   hvsupport.pl \
   $(schema_DATA)
@@ -262,6 +311,10 @@ CLEANFILES = \
   $(apilxchtml) \
   $(internals_html) \
   $(kbase_html) \
+  $(manpages_html) \
+  $(man1_MANS) \
+  $(man7_MANS) \
+  $(man8_MANS) \
   $(api_DATA) \
   $(dot_html_generated_in) \
   aclperms.htmlinc
@@ -298,6 +351,13 @@ EXTRA_DIST += \
 %.png: %.fig
 	convert -rotate 90 $< $@
 
+manpages/%.html.in: manpages/%.rst
+	$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
+	 grep -v '^:Manual ' < $< | \
+	  sed -e 's|SYSCONFDIR|$(sysconfdir)|g' \
+	     -e 's|RUNSTATEDIR|$(runstatedir)|g' | \
+	  $(RST2HTML) > $@
+
 %.html.in: %.rst
 	$(AM_V_GEN)$(MKDIR_P) `dirname $@` && \
 	  $(RST2HTML) $< > $@
diff --git a/docs/docs.html.in b/docs/docs.html.in
index f441769617..fbf35234d4 100644
--- a/docs/docs.html.in
+++ b/docs/docs.html.in
@@ -9,6 +9,9 @@
         <dt><a href="apps.html">Applications</a></dt>
         <dd>Applications known to use libvirt</dd>
 
+        <dt><a href="manpages/index.html">Manual pages</a></dt>
+        <dd>Manual pages for libvirt tools / daemons</dd>
+
         <dt><a href="windows.html">Windows</a></dt>
         <dd>Downloads for Windows</dd>
 
diff --git a/docs/manpages/index.rst b/docs/manpages/index.rst
new file mode 100644
index 0000000000..11c72135e8
--- /dev/null
+++ b/docs/manpages/index.rst
@@ -0,0 +1,3 @@
+====================
+Libvirt Manual Pages
+====================
diff --git a/m4/virt-external-programs.m4 b/m4/virt-external-programs.m4
index ed634a4c73..9b128382fa 100644
--- a/m4/virt-external-programs.m4
+++ b/m4/virt-external-programs.m4
@@ -38,6 +38,11 @@ AC_DEFUN([LIBVIRT_CHECK_EXTERNAL_PROGRAMS], [
   then
     AC_MSG_ERROR("rst2html is required to build libvirt")
   fi
+  AC_PATH_PROGS([RST2MAN], [rst2man rst2man.py rst2man-3], [])
+  if test -z "$RST2MAN"
+  then
+    AC_MSG_ERROR("rst2man is required to build libvirt")
+  fi
   AC_PATH_PROG([AUGPARSE], [augparse], [/usr/bin/augparse])
   AC_PROG_MKDIR_P
   AC_PROG_LN_S
-- 
2.23.0