Re: [ovs-dev] [PATCH 4/6] doc: Convert ovs-vlan-test to rST

2017-04-18 Thread Stephen Finucane 
On Thu, 2017-04-13 at 21:43 -0700, Ben Pfaff wrote:
> From: Stephen Finucane 
> 
> 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

This mostly looks good to me. Some comments below but nothing I'd block
on.

Acked-by: Stephen Finucane 

> Signed-off-by: Stephen Finucane 
> Signed-off-by: Ben Pfaff 
> ---
>  Documentation/automake.mk  |  84
> +--
>  Documentation/conf.py  |   5 +-
>  .../internals/contributing/documentation-style.rst |   3 +-
>  Documentation/intro/install/documentation.rst  |   4 +-
>  Documentation/ref/index.rst|  16 ++-
>  Documentation/ref/ovs-vlan-test.8.rst  | 115
> +
>  debian/openvswitch-switch.manpages |   1 -
>  manpages.mk|  10 --
>  utilities/automake.mk  |   3 -
>  utilities/ovs-vlan-test.8.in   |  96 -
> 
>  10 files changed, 211 insertions(+), 126 deletions(-)
>  create mode 100644 Documentation/ref/ovs-vlan-test.8.rst
>  delete mode 100644 utilities/ovs-vlan-test.8.in
> 
> diff --git a/Documentation/automake.mk b/Documentation/automake.mk
> index 9911668c1ca9..762255277102 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))
>  
>  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
> +

I might have done something funky applying this, but I can see a '^L'
character (linefeed?) on this line. Might be worth watching for.

> +# 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;

[ovs-dev] [PATCH 4/6] doc: Convert ovs-vlan-test to rST

2017-04-13 Thread Ben Pfaff 
From: Stephen Finucane 

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 
Signed-off-by: Ben Pfaff 
---
 Documentation/automake.mk  |  84 +--
 Documentation/conf.py  |   5 +-
 .../internals/contributing/documentation-style.rst |   3 +-
 Documentation/intro/install/documentation.rst  |   4 +-
 Documentation/ref/index.rst|  16 ++-
 Documentation/ref/ovs-vlan-test.8.rst  | 115 +
 debian/openvswitch-switch.manpages |   1 -
 manpages.mk|  10 --
 utilities/automake.mk  |   3 -
 utilities/ovs-vlan-test.8.in   |  96 -
 10 files changed, 211 insertions(+), 126 deletions(-)
 create mode 100644 Documentation/ref/ovs-vlan-test.8.rst
 delete mode 100644 utilities/ovs-vlan-test.8.in

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 9911668c1ca9..762255277102 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))
 
 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)