From 9599ffe65d9dcd4b3aa780d346eccd1e760890bf Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Tue, 13 Jun 2017 15:55:33 -0400 Subject: 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 --- doc/source/command-beta.rst | 106 -------------------------------------------- 1 file changed, 106 deletions(-) delete mode 100644 doc/source/command-beta.rst (limited to 'doc/source/command-beta.rst') diff --git a/doc/source/command-beta.rst b/doc/source/command-beta.rst deleted file mode 100644 index 669ef201..00000000 --- a/doc/source/command-beta.rst +++ /dev/null @@ -1,106 +0,0 @@ -============ -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 - - .. 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='', - help=_("Example") - ) -- cgit v1.2.1