Add "--network-segment" option to "subnet create"

Add "--network-segment" option to the "subnet create" command.
This is a beta command option and subject to change. Use global
option "--os-beta-command" to enable this option.

This patch set also provides a devref update for beta command
options.

Change-Id: I4d0fbe079b2a873307364c41c22ce9ba88e632e6
Partially-Implements: blueprint routed-networks

2 files changed, 57 insertions, 10 deletions

diff --git a/doc/source/command-beta.rst b/doc/source/command-beta.rst
index f0a4f851..bc8c04c5 100644
--- a/doc/source/command-beta.rst
+++ b/doc/source/command-beta.rst
@@ -12,23 +12,29 @@ To address these challenges, an OpenStackClient command may
 be labeled as a beta command according to the guidelines
 below. Such commands may introduce backwards incompatible
 changes and may use REST API enhancements not yet released.
+This also applies to command options associated with the beta
+command object.
 
-See the examples below on how to label a command as a beta
-by updating the command documentation, help and implementation.
+See the examples below on how to label an entire command or
+a specific option as a beta by updating the documentation
+and implementation.
 
-The initial release note must label the new command as a beta.
-No further release notes are required until the command
-is no longer a beta. At which time, the command beta label
-or the command itself must be removed and a new release note
+The initial release note must label the new command or option
+as a beta. No further release notes are required until the command
+or option is no longer a beta. At which time, the beta label or
+the command or option itself must be removed and a new release note
 must be provided.
 
+Beta Command Example
+--------------------
+
 Documentation
--------------
+~~~~~~~~~~~~~
 
 The command documentation must label the command as a beta.
 
 example list
-~~~~~~~~~~~~
+++++++++++++
 
 List examples
 
@@ -42,7 +48,7 @@ List examples
     os example list
 
 Help
-----
+~~~~
 
 The command help must label the command as a beta.
 
@@ -57,7 +63,7 @@ The command help must label the command as a beta.
         """
 
 Implementation
---------------
+~~~~~~~~~~~~~~
 
 The command must raise a ``CommandError`` exception if beta commands
 are not enabled via ``--os-beta-command`` global option.
@@ -66,3 +72,35 @@ are not enabled via ``--os-beta-command`` global option.
 
     def take_action(self, parsed_args):
         self.validate_os_beta_command_enabled()
+
+Beta Option Example
+-------------------
+
+Documentation
+~~~~~~~~~~~~~
+
+The option documentation must label the option as a beta.
+
+.. option:: --example <example>
+
+     Example
+
+     .. caution:: This is a beta command option and subject
+                  to change. Use global option ``--os-beta-command``
+                  to enable this command option.
+
+Implementation
+~~~~~~~~~~~~~~
+
+The option must not be added if beta commands are not
+enabled via ``--os-beta-command`` global option.
+
+.. code-block:: python
+
+    def get_parser(self, prog_name):
+        if self.app.options.os_beta_command:
+            parser.add_argument(
+                '--example',
+                metavar='<example>',
+                help=_("Example")
+            )
diff --git a/doc/source/command-objects/subnet.rst b/doc/source/command-objects/subnet.rst
index ff6354e6..dd54408b 100644
--- a/doc/source/command-objects/subnet.rst
+++ b/doc/source/command-objects/subnet.rst
@@ -28,6 +28,7 @@ Create new subnet
         [--ip-version {4,6}]
         [--ipv6-ra-mode {dhcpv6-stateful,dhcpv6-stateless,slaac}]
         [--ipv6-address-mode {dhcpv6-stateful,dhcpv6-stateless,slaac}]
+        [--network-segment <network-segment>]
         --network <network>
         <name>
 
@@ -107,6 +108,14 @@ Create new subnet
 
      IPv6 address mode, valid modes: [dhcpv6-stateful, dhcpv6-stateless, slaac]
 
+.. option:: --network-segment <network-segment>
+
+     Network segment to associate with this subnet (ID only)
+
+     .. caution:: This is a beta command option and subject
+                  to change. Use global option ``--os-beta-command``
+                  to enable this command option.
+
 .. option:: --network <network>
 
      Network this subnet belongs to (name or ID)