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>

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
+	$(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b man $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/man && touch $@
-CLEANFILES += htmldocs-check
+ALL_LOCAL += docs-check
+CLEANFILES += docs-check
 
 check-docs:
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/linkcheck
 
 clean-docs:
-	rm -rf $(SPHINXBUILDDIR)/doctrees
+	rm -rf $(SPHINXBUILDDIR)
-	rm -rf $(SPHINXBUILDDIR)/html
-	rm -rf $(SPHINXBUILDDIR)/linkcheck
 	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

Documentation/conf.py

@@ -331,8 +331,9 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'openvswitch', u'Open vSwitch Documentation',
+    ('ref/ovs-vlan-test.8', 'ovs-vlan-test',
-     [author], 1)
+     u'Check Linux drivers for problems with vlan traffic',
+     [author], 8)
 ]
 
 # If true, show URL addresses after external links.

Documentation/internals/contributing/documentation-style.rst

@@ -347,7 +347,8 @@ In addition to the above, man pages have some specific requirements:
 - The man page must be included in the list of man page documents found in
   `conf.py`__
 
-Refer to existing man pages for worked examples.
+Refer to existing man pages, such as :doc:`/ref/ovs-vlan-test.8` for a worked
+example.
 
 __ http://www.sphinx-doc.org/en/stable/domains.html#directive-program
 __ http://www.sphinx-doc.org/en/stable/domains.html#directive-option

Documentation/intro/install/documentation.rst

@@ -74,11 +74,11 @@ Building
 Once Sphinx installed, the documentation can be built using the provided
 Makefile targets::
 
-    $ make htmldocs-check
+    $ make docs-check
 
 .. important::
 
-   The ``htmldocs-check`` target will fail if there are any syntax errors.
+   The ``docs-check`` target will fail if there are any syntax errors.
    However, it won't catch more succint issues such as style or grammar issues.
    As a result, you should always inspect changes visually to ensure the result
    is as intended.

Documentation/ref/index.rst

@@ -30,10 +30,18 @@ Reference Guide
 Man Pages
 ---------
 
-.. TODO(stephenfin): Investigate some way to get the manpages into rST format.
+.. TODO(stephenfin): Remove the below notice once everything is converted to
-   The most viable option seems to be writing them all in rST, converting them
+   rST
-   to roff format and storing both the rST and roff formatted docs in version
+
-   control.
+The following man pages are written in rST and converted to roff at compile
+time:
+
+.. toctree::
+   :maxdepth: 3
+
+   ovs-vlan-test.8
+
+The remainder are still in roff format can be found below:
 
 .. list-table::
 

Documentation/ref/ovs-vlan-test.8.rst

@@ -0,0 +1,115 @@
+=============
+ovs-vlan-test
+=============
+
+Synopsis
+========
+
+**ovs-vlan-test** [**-s** | **--server**] *control_ip* *vlan_ip*
+
+Description
+===========
+
+.. TODO(stephenfin): Add the `:program:` prefixes to `ovs-test` once that doc
+   is converted
+
+The :program:`ovs-vlan-test` utility has some limitations, for example, it does
+not use TCP in its tests. Also it does not take into account MTU to detect
+potential edge cases. To overcome those limitations a new tool was developed -
+`ovs-test`. `ovs-test` is currently supported only on Debian so, if possible,
+try to use that on instead of :program:`ovs-vlan-test`.
+
+The :program:`ovs-vlan-test` program may be used to check for problems sending
+802.1Q traffic which may occur when running Open vSwitch. These problems can
+occur when Open vSwitch is used to send 802.1Q traffic through physical
+interfaces running certain drivers of certain Linux kernel versions. To run a
+test, configure Open vSwitch to tag traffic originating from `vlan_ip` and
+forward it out the target interface. Then run the :program:`ovs-vlan-test` in
+client mode connecting to an :program:`ovs-vlan-test` server.
+:program:`ovs-vlan-test` will display "OK" if it did not detect problems.
+
+Some examples of the types of problems that may be encountered are:
+
+- When NICs use VLAN stripping on receive they must pass a pointer to a
+  `vlan_group` when reporting the stripped tag to the networking core. If no
+  `vlan_group` is in use then some drivers just drop the extracted tag.
+  Drivers are supposed to only enable stripping if a `vlan_group` is registered
+  but not all of them do that.
+
+- On receive, some drivers handle priority tagged packets specially and don't
+  pass the tag onto the network stack at all, so Open vSwitch never has a
+  chance to see it.
+
+- Some drivers size their receive buffers based on whether a `vlan_group` is
+  enabled, meaning that a maximum size packet with a VLAN tag will not fit if
+  no `vlan_group` is configured.
+
+- On transmit, some drivers expect that VLAN acceleration will be used if it is
+  available, which can only be done if a `vlan_group` is configured. In these
+  cases, the driver may fail to parse the packet and correctly setup checksum
+  offloading or TSO.
+
+Client Mode
+  An :program:`ovs-vlan-test` client may be run on a host to check for VLAN
+  connectivity problems. The client must be able to establish HTTP connections
+  with an :program:`ovs-vlan-test` server located at the specified `control_ip`
+  address. UDP traffic sourced at `vlan_ip` should be tagged and directed out
+  the interface whose connectivity is being tested.
+
+Server Mode
+  To conduct tests, an :program:`ovs-vlan-test` server must be running on a
+  host known not to have VLAN connectivity problems. The server must have a
+  `control_ip` on a non-VLAN network which clients can establish connectivity
+  with. It must also have a `vlan_ip` address on a VLAN network which clients
+  will use to test their VLAN connectivity. Multiple clients may test against a
+  single :program:`ovs-vlan-test` server concurrently.
+
+Options
+=======
+
+.. program:: ovs-vlan-test
+
+.. option:: -s, --server
+
+    Run in server mode.
+
+.. option:: -h, --help
+
+    Prints a brief help message to the console.
+
+.. option:: -V, --version
+
+    Prints version information to the console.
+
+Examples
+========
+
+Display the Linux kernel version and driver of `eth1`::
+
+   uname -r
+   ethtool -i eth1
+
+Set up a bridge which forwards traffic originating from `1.2.3.4` out `eth1`
+with VLAN tag 10::
+
+    ovs-vsctl -- add-br vlan-br \
+      -- add-port vlan-br eth1 \
+      -- add-port vlan-br vlan-br-tag tag=10 \
+      -- set Interface vlan-br-tag type=internal
+    ifconfig vlan-br-tag up 1.2.3.4
+
+Run an :program:`ovs-vlan-test` server listening for client control traffic on
+`172.16.0.142` port `8080` and VLAN traffic on the default port of `1.2.3.3`::
+
+    ovs-vlan-test -s 172.16.0.142:8080 1.2.3.3
+
+Run an :program:`ovs-vlan-test` client with a control server located at
+`172.16.0.142` port `8080` and a local VLAN IP of `1.2.3.4`::
+
+    ovs-vlan-test 172.16.0.142:8080 1.2.3.4
+
+See Also
+========
+
+`ovs-vswitchd(8)`, `ovs-ofctl(8)`, `ovs-vsctl(8)`, `ovs-test(8)`, `ethtool(8)`,
+`uname(1)`

debian/openvswitch-switch.manpages

@@ -5,7 +5,6 @@ utilities/ovs-dpctl.8
 utilities/ovs-pcap.1
 utilities/ovs-tcpdump.8
 utilities/ovs-tcpundump.1
-utilities/ovs-vlan-test.8
 utilities/ovs-vsctl.8
 vswitchd/ovs-vswitchd.8
 vswitchd/ovs-vswitchd.conf.db.5

manpages.mk

@@ -244,16 +244,6 @@ utilities/ovs-vlan-bug-workaround.8.in:
 lib/common.man:
 utilities/ovs-vlan-bugs.man:
 
-utilities/ovs-vlan-test.8: \
-	utilities/ovs-vlan-test.8.in \
-	lib/common-syn.man \
-	lib/common.man \
-	utilities/ovs-vlan-bugs.man
-utilities/ovs-vlan-test.8.in:
-lib/common-syn.man:
-lib/common.man:
-utilities/ovs-vlan-bugs.man:
-
 utilities/ovs-vsctl.8: \
 	utilities/ovs-vsctl.8.in \
 	lib/common.man \

utilities/automake.mk

@@ -72,7 +72,6 @@ MAN_ROOTS += \
 	utilities/ovs-tcpundump.1.in \
 	utilities/ovs-vlan-bug-workaround.8.in \
 	utilities/ovs-test.8.in \
-	utilities/ovs-vlan-test.8.in \
 	utilities/ovs-vsctl.8.in
 MAN_FRAGMENTS += utilities/ovs-vlan-bugs.man
 CLEANFILES += \
@@ -101,7 +100,6 @@ CLEANFILES += \
 	utilities/ovs-test \
 	utilities/ovs-test.8 \
 	utilities/ovs-vlan-test \
-	utilities/ovs-vlan-test.8 \
 	utilities/ovs-vlan-bug-workaround.8 \
 	utilities/ovs-vsctl.8
 
@@ -120,7 +118,6 @@ man_MANS += \
 	utilities/ovs-tcpundump.1 \
 	utilities/ovs-vlan-bug-workaround.8 \
 	utilities/ovs-test.8 \
-	utilities/ovs-vlan-test.8 \
 	utilities/ovs-vsctl.8
 
 utilities_ovs_appctl_SOURCES = utilities/ovs-appctl.c

utilities/ovs-vlan-test.8.in

@@ -1,96 +0,0 @@
-.de IQ
-.  br
-.  ns
-.  IP "\\$1"
-..
-.TH ovs\-vlan\-test 1 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
-.
-.SH NAME
-\fBovs\-vlan\-test\fR \- check Linux drivers for problems with vlan traffic
-.
-.SH SYNOPSIS
-\fBovs\-vlan\-test\fR [\fB\-s\fR | \fB\-\-server\fR] \fIcontrol_ip\fR \fIvlan_ip\fR
-.so lib/common-syn.man
-.
-.SH DESCRIPTION
-The \fBovs\-vlan\-test\fR utility has some limitations, for example, it does
-not use TCP in its tests. Also it does not take into account MTU to detect
-potential edge cases. To overcome those limitations a new tool was
-developed \- \fBovs\-test\fR. \fBovs\-test\fR is currently supported only
-on Debian so, if possible try to use that on instead of \fBovs\-vlan\-test\fR.
-.PP
-The \fBovs\-vlan\-test\fR program may be used to check for problems sending
-802.1Q traffic which may occur when running Open vSwitch. These problems can
-occur when Open vSwitch is used to send 802.1Q traffic through physical
-interfaces running certain drivers of certain Linux kernel versions. To run a
-test, configure Open vSwitch to tag traffic originating from \fIvlan_ip\fR and
-forward it out the target interface. Then run the \fBovs\-vlan\-test\fR in
-client mode connecting to an \fBovs\-vlan\-test\fR server.
-\fBovs\-vlan\-test\fR will display "OK" if it did not detect problems.
-.PP
-Some examples of the types of problems that may be encountered are:
-.so utilities/ovs-vlan-bugs.man
-.
-.SS "Client Mode"
-An \fBovs\-vlan\-test\fR client may be run on a host to check for VLAN
-connectivity problems.  The client must be able to establish HTTP connections
-with an \fBovs\-vlan\-test\fR server located at the specified \fIcontrol_ip\fR
-address.  UDP traffic sourced at \fIvlan_ip\fR should be tagged and directed out
-the interface whose connectivity is being tested.
-.
-.SS "Server Mode"
-To conduct tests, an \fBovs\-vlan\-test\fR server must be running on a host
-known not to have VLAN connectivity problems.  The server must have a
-\fIcontrol_ip\fR on a non\-VLAN network which clients can establish
-connectivity with.  It must also have a \fIvlan_ip\fR address on a VLAN network
-which clients will use to test their VLAN connectivity.  Multiple clients may
-test against a single \fBovs\-vlan\-test\fR server concurrently.
-.
-.SH OPTIONS
-.
-.IP "\fB\-s\fR"
-.IQ "\fB\-\-server\fR"
-Run in server mode.
-.
-.so lib/common.man
-.SH EXAMPLES
-Display the Linux kernel version and driver of \fBeth1\fR.
-.IP
-.B uname \-r
-.IP
-.B ethtool \-i eth1
-.
-.PP
-Set up a bridge which forwards traffic originating from \fB1.2.3.4\fR out
-\fBeth1\fR with VLAN tag 10.
-.IP
-.B ovs\-vsctl \-\- add\-br vlan\-br \(rs
-.IP
-.B \-\- add\-port vlan\-br eth1 \(rs
-.IP
-.B \-\- add\-port vlan\-br vlan\-br\-tag tag=10 \(rs
-.IP
-.B \-\- set Interface vlan\-br\-tag type=internal
-.IP
-.B ifconfig vlan\-br\-tag up 1.2.3.4
-.
-.PP
-Run an \fBovs\-vlan\-test\fR server listening for client control traffic on
-172.16.0.142 port 8080 and VLAN traffic on the default port of 1.2.3.3.
-.IP
-.B ovs\-vlan\-test \-s 172.16.0.142:8080 1.2.3.3
-.
-.PP
-Run an \fBovs\-vlan\-test\fR client with a control server located at
-172.16.0.142 port 8080 and a local VLAN ip of 1.2.3.4.
-.IP
-.B ovs\-vlan\-test 172.16.0.142:8080 1.2.3.4
-.
-.SH SEE ALSO
-.
-.BR ovs\-vswitchd (8),
-.BR ovs\-ofctl (8),
-.BR ovs\-vsctl (8),
-.BR ovs\-test (8),
-.BR ethtool (8),
-.BR uname (1)