neutron: autogenerate docs

$namespace = openstack.network.v2

The subcommand documents for $namespace were hardcoded and thus prone to
drift over time. This commit removes the hardcoded content and uses the
autoprogram-cliff directive to generate them automatically from the
subcommand configuration classes.

This one turned out to be quite involved, because we support both
neutron and nova-network. When running in a real cloud, the command
classes detect whether the neutron service is present, assume
nova-network if that service is not found, and only add parser options
relevant to the detected service. But the docs need to present both sets
of options. This was easy enough when they were hardcoded, but required
a bit of additional infrastructure for generated docs.

Change-Id: I426261eb1d86bcc68656aabd61f10b7f082da402

1 files changed, 14 insertions, 418 deletions

diff --git a/doc/source/cli/command-objects/subnet.rst b/doc/source/cli/command-objects/subnet.rst
index 73e656d8..488fc5a2 100644
--- a/doc/source/cli/command-objects/subnet.rst
+++ b/doc/source/cli/command-objects/subnet.rst
@@ -8,427 +8,23 @@ network.
 
 Network v2
 
-subnet create
--------------
+.. NOTE(efried): have to list these out one by one; 'subnet *' pulls in
+                 subnet pool *.
 
-Create new subnet
+.. autoprogram-cliff:: openstack.network.v2
+   :command: subnet create
 
-.. program:: subnet create
-.. code:: bash
+.. autoprogram-cliff:: openstack.network.v2
+   :command: subnet delete
 
-    openstack subnet create
-        [--project <project> [--project-domain <project-domain>]]
-        [--subnet-pool <subnet-pool> | --use-default-subnet-pool [--prefix-length <prefix-length>] | --use-prefix-delegation]
-        [--subnet-range <subnet-range>]
-        [--allocation-pool start=<ip-address>,end=<ip-address>]
-        [--dhcp | --no-dhcp]
-        [--dns-nameserver <dns-nameserver>]
-        [--gateway <gateway>]
-        [--host-route destination=<subnet>,gateway=<ip-address>]
-        [--ip-version {4,6}]
-        [--description <description>]
-        [--ipv6-ra-mode {dhcpv6-stateful,dhcpv6-stateless,slaac}]
-        [--ipv6-address-mode {dhcpv6-stateful,dhcpv6-stateless,slaac}]
-        [--network-segment <network-segment>]
-        [--service-type <service-type>]
-        [--tag <tag> | --no-tag]
-        --network <network>
-        <name>
+.. autoprogram-cliff:: openstack.network.v2
+   :command: subnet list
 
-.. option:: --project <project>
+.. autoprogram-cliff:: openstack.network.v2
+   :command: subnet set
 
-    Owner's project (name or ID)
+.. autoprogram-cliff:: openstack.network.v2
+   :command: subnet show
 
-.. option:: --project-domain <project-domain>
-
-    Domain the project belongs to (name or ID).
-    This can be used in case collisions between project names exist.
-
-.. option:: --subnet-pool <subnet-pool>
-
-    Subnet pool from which this subnet will obtain a CIDR (name or ID)
-
-.. option:: --use-prefix-delegation
-
-    Use 'prefix-delegation' if IP is IPv6 format and IP would be delegated
-    externally
-
-.. option:: --use-default-subnet-pool
-
-    Use default subnet pool for :option:`--ip-version`
-
-.. option:: --prefix-length <prefix-length>
-
-    Prefix length for subnet allocation from subnet pool
-
-.. option:: --subnet-range <subnet-range>
-
-    Subnet range in CIDR notation
-    (required if :option:`--subnet-pool` is not specified, optional otherwise)
-
-.. option:: --allocation-pool start=<ip-address>,end=<ip-address>
-
-    Allocation pool IP addresses for this subnet e.g.:
-    ``start=192.168.199.2,end=192.168.199.254``
-    (repeat option to add multiple IP addresses)
-
-.. option:: --dhcp
-
-     Enable DHCP (default)
-
-.. option:: --no-dhcp
-
-     Disable DHCP
-
-.. option:: --dns-nameserver <dns-nameserver>
-
-     DNS server for this subnet (repeat option to set multiple DNS servers)
-
-.. option:: --gateway <gateway>
-
-     Specify a gateway for the subnet.  The three options are:
-     <ip-address>: Specific IP address to use as the gateway,
-     'auto': Gateway address should automatically be chosen from
-     within the subnet itself, 'none': This subnet will not use
-     a gateway, e.g.: ``--gateway 192.168.9.1``, ``--gateway auto``,
-     ``--gateway none`` (default is 'auto').
-
-.. option:: --host-route destination=<subnet>,gateway=<ip-address>
-
-     Additional route for this subnet e.g.:
-     ``destination=10.10.0.0/16,gateway=192.168.71.254``
-     destination: destination subnet (in CIDR notation)
-     gateway: nexthop IP address
-     (repeat option to add multiple routes)
-
-.. option:: --ip-version {4,6}
-
-     IP version (default is 4).  Note that when subnet pool is specified,
-     IP version is determined from the subnet pool and this option
-     is ignored.
-
-.. option:: --description <description>
-
-     Set subnet description
-
-.. option:: --ipv6-ra-mode {dhcpv6-stateful,dhcpv6-stateless,slaac}
-
-     IPv6 RA (Router Advertisement) mode,
-     valid modes: [dhcpv6-stateful, dhcpv6-stateless, slaac]
-
-.. option:: --ipv6-address-mode {dhcpv6-stateful,dhcpv6-stateless,slaac}
-
-     IPv6 address mode, valid modes: [dhcpv6-stateful, dhcpv6-stateless, slaac]
-
-.. option:: --network-segment <network-segment>
-
-     Network segment to associate with this subnet (name or ID)
-
-.. option:: --service-type <service-type>
-
-     Service type for this subnet e.g.:
-     ``network:floatingip_agent_gateway``.
-     Must be a valid device owner value for a network port
-     (repeat option to set multiple service types)
-
-.. option:: --tag <tag>
-
-    Tag to be added to the subnet (repeat option to set multiple tags)
-
-.. option:: --no-tag
-
-    No tags associated with the subnet
-
-.. option:: --network <network>
-
-     Network this subnet belongs to (name or ID)
-
-.. _subnet_create-name:
-.. describe:: <name>
-
-     Name of subnet to create
-
-subnet delete
--------------
-
-Delete subnet(s)
-
-.. program:: subnet delete
-.. code:: bash
-
-    openstack subnet delete
-        <subnet> [<subnet> ...]
-
-.. _subnet_delete-subnet:
-.. describe:: <subnet>
-
-    Subnet(s) to delete (name or ID)
-
-subnet list
------------
-
-List subnets
-
-.. program:: subnet list
-.. code:: bash
-
-    openstack subnet list
-        [--long]
-        [--ip-version {4,6}]
-        [--dhcp | --no-dhcp]
-        [--project <project> [--project-domain <project-domain>]]
-        [--network <network>]
-        [--gateway <gateway>]
-        [--name <name>]
-        [--subnet-range <subnet-range>]
-        [--tags <tag>[,<tag>,...]] [--any-tags <tag>[,<tag>,...]]
-        [--not-tags <tag>[,<tag>,...]] [--not-any-tags <tag>[,<tag>,...]]
-
-.. option:: --long
-
-    List additional fields in output
-
-.. option:: --ip-version {4, 6}
-
-    List only subnets of given IP version in output.
-    Allowed values for IP version are 4 and 6.
-
-.. option:: --dhcp
-
-    List subnets which have DHCP enabled
-
-.. option:: --no-dhcp
-
-    List subnets which have DHCP disabled
-
-.. option:: --service-type <service-type>
-
-    List only subnets of a given service type in output
-    e.g.: ``network:floatingip_agent_gateway``.
-    Must be a valid device owner value for a network port
-    (repeat option to list multiple service types)
-
-.. option:: --project <project>
-
-    List only subnets which belong to a given project in output (name or ID)
-
-.. option:: --project-domain <project-domain>
-
-    Domain the project belongs to (name or ID).
-    This can be used in case collisions between project names exist.
-
-.. option:: --network <network>
-
-    List only subnets which belong to a given network in output (name or ID)
-
-.. option:: --gateway <gateway>
-
-    List only subnets of given gateway IP in output
-
-.. option:: --name <name>
-
-    List only subnets of given name in output
-
-.. option:: --subnet-range <subnet-range>
-
-    List only subnets of given subnet range (in CIDR notation) in output
-    e.g.: ``--subnet-range 10.10.0.0/16``
-
-.. option:: --tags <tag>[,<tag>,...]
-
-    List subnets which have all given tag(s)
-
-.. option:: --any-tags <tag>[,<tag>,...]
-
-    List subnets which have any given tag(s)
-
-.. option:: --not-tags <tag>[,<tag>,...]
-
-    Exclude subnets which have all given tag(s)
-
-.. option:: --not-any-tags <tag>[,<tag>,...]
-
-    Exclude subnets which have any given tag(s)
-
-subnet set
-----------
-
-Set subnet properties
-
-.. program:: subnet set
-.. code:: bash
-
-    openstack subnet set
-        [--allocation-pool start=<ip-address>,end=<ip-address>]
-        [--no-allocation-pool]
-        [--dhcp | --no-dhcp]
-        [--dns-nameserver <dns-nameserver>]
-        [--no-dns-nameserver]
-        [--gateway <gateway-ip>]
-        [--network-segment <network-segment>]
-        [--host-route destination=<subnet>,gateway=<ip-address>]
-        [--no-host-route]
-        [--service-type <service-type>]
-        [--name <new-name>]
-        [--description <description>]
-        [--tag <tag>] [--no-tag]
-        <subnet>
-
-.. option:: --allocation-pool start=<ip-address>,end=<ip-address>
-
-    Allocation pool IP addresses for this subnet e.g.:
-    ``start=192.168.199.2,end=192.168.199.254``
-    (repeat option to add multiple IP addresses)
-
-.. option:: --no-allocation-pool
-
-     Clear associated allocation pools from this subnet.
-     Specify both :option:`--allocation-pool` and :option:`--no-allocation-pool`
-     to overwrite the current allocation pool information.
-
-.. option:: --dhcp
-
-     Enable DHCP
-
-.. option:: --no-dhcp
-
-     Disable DHCP
-
-.. option:: --dns-nameserver <dns-nameserver>
-
-     DNS server for this subnet (repeat option to set multiple DNS servers)
-
-.. option:: --no-dns-nameservers
-
-     Clear existing information of DNS servers.
-     Specify both :option:`--dns-nameserver` and :option:`--no-dns-nameservers`
-     to overwrite the current DNS server information.
-
-.. option:: --gateway <gateway>
-
-     Specify a gateway for the subnet. The options are:
-     <ip-address>: Specific IP address to use as the gateway,
-     'none': This subnet will not use a gateway,
-     e.g.: ``--gateway 192.168.9.1``, ``--gateway none``.
-
-.. option:: --network-segment <network-segment>
-
-     Network segment to associate with this subnet (name or ID). It is only
-     allowed to set the segment if the current value is `None`, the network
-     must also have only one segment and only one subnet can exist on the
-     network.
-
-.. option:: --host-route destination=<subnet>,gateway=<ip-address>
-
-     Additional route for this subnet e.g.:
-     ``destination=10.10.0.0/16,gateway=192.168.71.254``
-     destination: destination subnet (in CIDR notation)
-     gateway: nexthop IP address
-
-.. option:: --no-host-route
-
-     Clear associated host routes from this subnet.
-     Specify both :option:`--host-route` and :option:`--no-host-route`
-     to overwrite the current host route information.
-
-.. option:: --service-type <service-type>
-
-     Service type for this subnet e.g.:
-     ``network:floatingip_agent_gateway``.
-     Must be a valid device owner value for a network port
-     (repeat option to set multiple service types)
-
-.. option:: --description <description>
-
-     Set subnet description
-
-.. option:: --name
-
-     Updated name of the subnet
-
-.. option:: --tag <tag>
-
-    Tag to be added to the subnet (repeat option to set multiple tags)
-
-.. option:: --no-tag
-
-    Clear tags associated with the subnet. Specify both --tag
-    and --no-tag to overwrite current tags
-
-.. _subnet_set-subnet:
-.. describe:: <subnet>
-
-    Subnet to modify (name or ID)
-
-
-subnet show
------------
-
-Display subnet details
-
-.. program:: subnet show
-.. code:: bash
-
-    openstack subnet show
-        <subnet>
-
-.. _subnet_show-subnet:
-.. describe:: <subnet>
-
-    Subnet to display (name or ID)
-
-subnet unset
-------------
-
-Unset subnet properties
-
-.. program:: subnet unset
-.. code:: bash
-
-    openstack subnet unset
-        [--allocation-pool start=<ip-address>,end=<ip-address> [...]]
-        [--dns-nameserver <dns-nameserver> [...]]
-        [--host-route destination=<subnet>,gateway=<ip-address> [...]]
-        [--service-type <service-type>]
-        [--tag <tag> | --all-tag]
-        <subnet>
-
-.. option:: --dns-nameserver <dns-nameserver>
-
-     DNS server to be removed from this subnet
-     (repeat option to unset multiple DNS servers)
-
-.. option:: --allocation-pool start=<ip-address>,end=<ip-address>
-
-    Allocation pool IP addresses to be removed from this
-    subnet e.g.: ``start=192.168.199.2,end=192.168.199.254``
-    (repeat option to unset multiple allocation pools)
-
-.. option:: --host-route destination=<subnet>,gateway=<ip-address>
-
-     Route to be removed from this subnet e.g.:
-     ``destination=10.10.0.0/16,gateway=192.168.71.254``
-     destination: destination subnet (in CIDR notation)
-     gateway: nexthop IP address
-     (repeat option to unset multiple host routes)
-
-.. option:: --service-type <service-type>
-
-     Service type to be removed from this subnet e.g.:
-     ``network:floatingip_agent_gateway``.
-     Must be a valid device owner value for a network port
-     (repeat option to unset multiple service types)
-
-.. option:: --tag <tag>
-
-    Tag to be removed from the subnet
-    (repeat option to remove multiple tags)
-
-.. option:: --all-tag
-
-    Clear all tags associated with the subnet
-
-.. _subnet_unset-subnet:
-.. describe:: <subnet>
-
-    Subnet to modify (name or ID)
+.. autoprogram-cliff:: openstack.network.v2
+   :command: subnet unset