From 40780d1a4ce1363994215065c5688d3d1ddcfe73 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 rst2man as a mandatory tool for building docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.

Reviewed-by: Cole Robinson <crobinso@redhat.com>
Signed-off-by: Daniel P. Berrangé <berrange@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 9462f77458..4e0568aef1 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 eddf3de6d5..b592f7d51f 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 952233c4b7..9046e3bf07 100644
--- a/m4/virt-external-programs.m4
+++ b/m4/virt-external-programs.m4
@@ -41,6 +41,11 @@ AC_DEFUN([LIBVIRT_CHECK_EXTERNAL_PROGRAMS], [
   then
     AC_MSG_ERROR("rst2html5/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
-- 
GitLab