doc: Convert ovs-vlan-test to rST

Let's start with a simple one that lets us focus on setting up most of
the required "infrastructure" for building man pages using Sphinx.

This changes the 'check-htmldocs' target to 'check-docs' as its now
responsible for building man page docs too.

Other than that, hurrah for (mostly) legible syntaxes.

[1] http://www.tldp.org/HOWTO/Man-Page/q2.html

Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Ben Pfaff <blp@ovn.org>

1 files changed, 77 insertions, 7 deletions

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 8d18bd971..737887d64 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -90,7 +90,8 @@ DOC_SOURCE = \
 	Documentation/internals/contributing/documentation-style.rst \
 	Documentation/internals/contributing/libopenvswitch-abi.rst \
 	Documentation/internals/contributing/submitting-patches.rst \
-	Documentation/requirements.txt
+	Documentation/requirements.txt \
+	$(addprefix Documentation/ref/,$(RST_MANPAGES))
 FLAKE8_PYFILES += Documentation/conf.py
 EXTRA_DIST += $(DOC_SOURCE)
 
@@ -110,20 +111,89 @@ sphinx_verbose_ = $(sphinx_verbose_@AM_DEFAULT_V@)
 sphinx_verbose_0 = -q
 
 if HAVE_SPHINX
-htmldocs-check: $(DOC_SOURCE)
+docs-check: $(DOC_SOURCE)
 	$(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html && touch $@
-ALL_LOCAL += htmldocs-check
-CLEANFILES += htmldocs-check
+	$(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b man $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/man && touch $@
+ALL_LOCAL += docs-check
+CLEANFILES += docs-check
 
 check-docs:
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/linkcheck
 
 clean-docs:
-	rm -rf $(SPHINXBUILDDIR)/doctrees
-	rm -rf $(SPHINXBUILDDIR)/html
-	rm -rf $(SPHINXBUILDDIR)/linkcheck
+	rm -rf $(SPHINXBUILDDIR)
 	rm -f docs-check
 CLEAN_LOCAL += clean-docs
 endif
 .PHONY: check-docs
 .PHONY: clean-docs
+
+# Installing manpages based on rST.
+#
+# The docs-check target converts the rST files listed in RST_MANPAGES
+# into nroff manpages in Documentation/_build/man.  The easiest way to
+# get these installed by "make install" is to write our own helper
+# rules.
+
+# rST formatted manpages under Documentation/ref.
+RST_MANPAGES = \
+	ovs-vlan-test.8.rst
+
+# The GNU standards say that these variables should control
+# installation directories for manpages in each section.  Automake
+# will define them for us only if it sees that a manpage in the
+# appropriate section is to be installed through its built-in feature.
+# Since we're working independently, for best safety, we need to
+# define them ourselves.
+man1dir = $(mandir)/man1
+man2dir = $(mandir)/man2
+man3dir = $(mandir)/man3
+man4dir = $(mandir)/man4
+man5dir = $(mandir)/man5
+man6dir = $(mandir)/man6
+man7dir = $(mandir)/man7
+man8dir = $(mandir)/man8
+man9dir = $(mandir)/man9
+
+# Set a shell variable for each manpage directory.
+set_mandirs = \
+	man1dir='$(man1dir)' \
+	man2dir='$(man2dir)' \
+	man3dir='$(man3dir)' \
+	man4dir='$(man4dir)' \
+	man5dir='$(man5dir)' \
+	man6dir='$(man6dir)' \
+	man7dir='$(man7dir)' \
+	man8dir='$(man8dir)' \
+	man9dir='$(man9dir)'
+
+# Given an $rst of "ovs-vlan-test.8.rst", sets $stem to
+# "ovs-vlan-test", $section to "8", and $mandir to $man8dir.
+extract_stem_and_section = \
+	stem=`echo "$$rst" | sed -n 's/^\(.*\)\.\([0-9]\).rst$$/\1/p'`; \
+	section=`echo "$$rst" | sed -n 's/^\(.*\)\.\([0-9]\).rst$$/\2/p'`; \
+	test -n "$$section" || { echo "$$rst: cannot infer manpage section from filename" 2>&1; continue; }; \
+	eval "mandir=\$$man$${section}dir"; \
+	test -n "$$mandir" || { echo "unknown directory for manpage section $$section"; continue; }
+
+if HAVE_SPHINX
+INSTALL_DATA_LOCAL += install-man-rst
+install-man-rst: docs-check
+	@$(set_mandirs); \
+	for rst in $(RST_MANPAGES); do \
+	    $(extract_stem_and_section); \
+	    echo " $(MKDIR_P) '$(DESTDIR)'\"$$mandir\""; \
+	    $(MKDIR_P) '$(DESTDIR)'"$$mandir"; \
+	    echo " $(INSTALL_DATA) $(SPHINXBUILDDIR)/man/$$stem.$$section '$(DESTDIR)'\"$$mandir/$$stem.$$section\""; \
+	    $(INSTALL_DATA) $(SPHINXBUILDDIR)/man/$$stem.$$section '$(DESTDIR)'"$$mandir/$$stem.$$section"; \
+	done
+endif
+
+UNINSTALL_LOCAL += uninstall-man-rst
+uninstall-man-rst:
+	@$(set_mandirs); \
+	for rst in $(RST_MANPAGES); do \
+	    $(extract_stem_and_section); \
+	    echo "rm -f '$(DESTDIR)'\"$$mandir/$$stem.$$section\""; \
+	    rm -f '$(DESTDIR)'"$$mandir/$$stem.$$section"; \
+	done