doc: Convert ovs-command-bashcomp.INSTALL to rST

Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Russell Bryant <russell@ovn.org>

3 files changed, 113 insertions, 90 deletions

diff --git a/utilities/automake.mk b/utilities/automake.mk
index 380418aca..014e477d1 100644
--- a/utilities/automake.mk
+++ b/utilities/automake.mk
@@ -37,11 +37,11 @@ noinst_SCRIPTS += utilities/ovs-sim
 
 utilities/ovs-lib: $(top_builddir)/config.status
 
-docs += utilities/ovs-command-bashcomp.INSTALL.md
+docs += utilities/ovs-command-bashcomp.INSTALL.rst
 EXTRA_DIST += \
 	utilities/ovs-appctl-bashcomp.bash \
 	utilities/ovs-check-dead-ifs.in \
-	utilities/ovs-command-bashcomp.INSTALL.md \
+	utilities/ovs-command-bashcomp.INSTALL.rst \
 	utilities/ovs-ctl.in \
 	utilities/ovs-dev.py \
 	utilities/ovs-docker \
diff --git a/utilities/ovs-command-bashcomp.INSTALL.md b/utilities/ovs-command-bashcomp.INSTALL.md
deleted file mode 100644
index 9bdef40f3..000000000
--- a/utilities/ovs-command-bashcomp.INSTALL.md
+++ /dev/null
@@ -1,88 +0,0 @@
-Using bash command-line completion scripts
-------------------------------------------
-
-There are two completion scripts available, ovs-appctl-bashcomp.bash
-and ovs-vsctl-bashcomp.bash respectively.
-
-ovs-appctl-bashcomp
--------------------
-
-   ovs-appctl-bashcomp.bash adds bash command-line completion support
-   for ovs-appctl, ovs-dpctl, ovs-ofctl and ovsdb-tool commands.
-
-   Features:
-   ---------
-
-      display available completion or complete on unfinished user input
-      (long option, subcommand, and argument).
-
-      once the subcommand (e.g. ofproto/trace) has been given, the
-      script will print the subcommand format.
-
-      the script can convert between keywords like 'bridge/port/interface/dp'
-      and the available record in ovsdb.
-
-   Limitations:
-   ------------
-
-      only support small set of important keywords
-      (dp, datapath, bridge, switch, port, interface, iface).
-
-      does not support parsing of nested options
-      (e.g. ovsdb-tool create [db [schema]]).
-
-      does not support expansion on repeatitive argument
-      (e.g. ovs-dpctl show [dp...]).
-
-      only support matching on long options, and only in the format
-      (--option [arg], i.e. should not use --option=[arg]).
-
-ovs-vsctl-bashcomp
--------------------
-
-   ovs-vsctl-bashcomp.bash adds bash command-line completion support
-   for ovs-vsctl command.
-
-   Features:
-   ---------
-
-      display available completion and complete on user input for
-      global/local options, command, and argument.
-
-      query database and expand keywords like 'table/record/column/key'
-      to available completions.
-
-      deal with argument relations like 'one and more', 'zero or one'.
-
-      complete multiple ovs-vsctl commands cascaded via '--'.
-
-   Limitations:
-   ------------
-
-      completion of very long ovs-vsctl command can take up to several
-      seconds.
-
-How to use:
------------
-
-   The bashcomp scripts should be placed at /etc/bash_completion.d/
-   to be available for all bash sessions.  Running 'make install'
-   will place the scripts to $(sysconfdir)/bash_completion.d/.  So user
-   should specify --sysconfdir=/etc at configuration.  Meanwhile, if OVS is
-   installed from packages, the scripts will automatically be placed inside
-   /etc/bash_completion.d/.
-
-   If you just want to run the scripts in one bash, you can remove them from
-   /etc/bash_completion.d/ and run the scripts via '. ovs-appctl-bashcomp.bash'
-   or '. ovs-vsctl-bashcomp.bash'.
-
-Test:
------
-
-   Unit tests are added in tests/completion.at and integrated into autotest
-   framework.  To run the tests, just do make check.
-
-Bug Reporting:
---------------
-
-Please report problems to bugs@openvswitch.org.
\ No newline at end of file
diff --git a/utilities/ovs-command-bashcomp.INSTALL.rst b/utilities/ovs-command-bashcomp.INSTALL.rst
new file mode 100644
index 000000000..6df60c65c
--- /dev/null
+++ b/utilities/ovs-command-bashcomp.INSTALL.rst
@@ -0,0 +1,111 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+====================================
+Bash command-line completion scripts
+====================================
+
+There are two completion scripts available, ovs-appctl-bashcomp.bash and
+ovs-vsctl-bashcomp.bash respectively.
+
+ovs-appctl-bashcomp
+-------------------
+
+ovs-appctl-bashcomp.bash adds bash command-line completion support for
+ovs-appctl, ovs-dpctl, ovs-ofctl and ovsdb-tool commands.
+
+Features
+~~~~~~~~
+
+- Display available completion or complete on unfinished user input (long
+  option, subcommand, and argument).
+
+- Subcommand hints
+
+- Convert between keywords like ``bridge``, ``port``, ``interface``, or ``dp``
+  and the available record in ovsdb.
+
+Limitations
+~~~~~~~~~~~
+
+- Only supports a small set of important keywords (``dp``, ``datapath``, ``bridge``, ``switch``,
+  ``port``, ``interface``, ``iface``).
+
+- Does not support parsing of nested options. For example:
+
+
+  ::
+
+      $ ovsdb-tool create [db [schema]]
+
+- Does not support expansion on repeated argument. For example:
+
+  ::
+
+      $ ovs-dpctl show [dp...]).
+
+- Only supports matching on long options, and only in the format ``--option
+  [arg]``. Do not use ``--option=[arg]``.
+
+ovs-vsctl-bashcomp
+-------------------
+
+ovs-vsctl-bashcomp.bash adds bash command-line completion support for ovs-vsctl
+command.
+
+Features
+~~~~~~~~
+
+- Display available completion and complete on user input for global/local
+  options, command, and argument.
+
+- Query database and expand keywords like ``table``, ``record``, ``column``, or
+  ``key``, to available completions.
+
+- Deal with argument relations like 'one and more', 'zero or one'.
+
+- Complete multiple ovs-vsctl commands cascaded via ``--``.
+
+Limitations
+~~~~~~~~~~~
+
+Completion of very long ``ovs-vsctl`` commands can take up to several seconds.
+
+Usage
+-----
+
+The bashcomp scripts should be placed at ``/etc/bash_completion.d/`` to be
+available for all bash sessions.  Running ``make install`` will place the
+scripts to ``$(sysconfdir)/bash_completion.d/``, thus, the user should specify
+``--sysconfdir=/etc`` at configuration.  If OVS is installed from packages, the
+scripts will automatically be placed inside ``/etc/bash_completion.d/``.
+
+If you just want to run the scripts in one bash, you can remove them from
+``/etc/bash_completion.d/`` and run the scripts via ``.
+ovs-appctl-bashcomp.bash`` or ``. ovs-vsctl-bashcomp.bash``.
+
+Tests
+-----
+
+Unit tests are added in ``tests/completion.at`` and integrated into autotest
+framework.  To run the tests, just run ``make check``.