提交 40780d1a 编写于 作者: D Daniel P. Berrangé

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: NCole Robinson <crobinso@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>
上级 8ffc4311
......@@ -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) $< > $@
......
......@@ -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>
......
====================
Libvirt Manual Pages
====================
......@@ -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
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册