reorganize existing documentation according to the new standard layout

Move existing content around based on the doc-migration specification.

Replace :doc: markup with :ref: to have sphinx keep track of where the
files move and generate valid hyperlinks.

Add a few toctrees and index pages for the new directories.

Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454
Change-Id: I253ee8f89d3ec40e39310c18bb87ed1d3d5de330
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

1 files changed, 108 insertions, 0 deletions

diff --git a/doc/source/contributor/command-beta.rst b/doc/source/contributor/command-beta.rst
new file mode 100644
index 00000000..40ede671
--- /dev/null
+++ b/doc/source/contributor/command-beta.rst
@@ -0,0 +1,108 @@
+.. _command-beta:
+
+============
+Command Beta
+============
+
+OpenStackClient releases do not always coincide with OpenStack
+releases. This creates challenges when developing new OpenStackClient
+commands for the current OpenStack release under development
+since there may not be an official release of the REST API
+enhancements necessary for the command. In addition, backwards
+compatibility may not be guaranteed until an official OpenStack release.
+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 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 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
+
+.. caution:: This is a beta command and subject to change.
+             Use global option ``--os-beta-command`` to
+             enable this command.
+
+.. program:: example list
+.. code:: bash
+
+    openstack example list
+
+Help
+~~~~
+
+The command help must label the command as a beta.
+
+.. code-block:: python
+
+    class ShowExample(command.ShowOne):
+        """Display example details
+
+           (Caution: This is a beta command and subject to change.
+            Use global option --os-beta-command to enable
+            this command)
+        """
+
+Implementation
+~~~~~~~~~~~~~~
+
+The command must raise a ``CommandError`` exception if beta commands
+are not enabled via ``--os-beta-command`` global option.
+
+.. code-block:: python
+
+    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")
+            )