docs: introduce rst2man as a mandatory tool for building docs

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>

diff --git a/docs/Makefile.am b/docs/Makefile.am
index 9462f774580eb0d20c033c3190a48ccd8205474c..4e0568aef12fa125de50b264aa76031a756f1e50 100644 (file)
--- 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 eddf3de6d5cd526f8b99d21aade997100cf423c5..b592f7d51f0ca4b00d1d829fcf7665dde30a0a66 100644 (file)
--- 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 (file)
index 0000000..11c7213
--- /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 952233c4b7e4ef42c0c49f77f668388cea93319e..9046e3bf07380de40e0ad35338cdc1cace41f037 100644 (file)
--- 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