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-wrappers.rst | 52 ----------------------------------------- 1 file changed, 52 deletions(-) delete mode 100644 doc/source/command-wrappers.rst (limited to 'doc/source/command-wrappers.rst') diff --git a/doc/source/command-wrappers.rst b/doc/source/command-wrappers.rst deleted file mode 100644 index 2a5d9223..00000000 --- a/doc/source/command-wrappers.rst +++ /dev/null @@ -1,52 +0,0 @@ -====================== -Command Class Wrappers -====================== - -When we want to deprecate a command, policy says we need to alert the user. -We do this with a message logged at WARNING level before any command output -is emitted. - -OpenStackClient command classes are derived from the ``cliff`` classes. -Cliff uses ``setuptools`` entry points for dispatching the parsed command -to the respective handler classes. This lends itself to modifying the -command execution at run-time. - -The obvious approach to adding the deprecation message would be to just add -the message to the command class ``take_action()`` method directly. But then -the various deprecations are scattered throughout the code base. If we -instead wrap the deprecated command class with a new class we can put all of -the wrappers into a separate, dedicated module. This also lets us leave the -original class unmodified and puts all of the deprecation bits in one place. - -This is an example of a minimal wrapper around a command class that logs a -deprecation message as a warning to the user then calls the original class. - -* Subclass the deprecated command. - -* Set class attribute ``deprecated`` to ``True`` to signal cliff to not - emit help text for this command. - -* Log the deprecation message at WARNING level and refer to the replacement - for the deprecated command in the log warning message. - -* Change the entry point class in ``setup.cfg`` to point to the new class. - -Example Deprecation Class -------------------------- - -.. code-block:: python - - class ListFooOld(ListFoo): - """List resources""" - - # This notifies cliff to not display the help for this command - deprecated = True - - log = logging.getLogger('deprecated') - - def take_action(self, parsed_args): - self.log.warning( - "%s is deprecated, use 'foobar list'", - getattr(self, 'cmd_name', 'this command'), - ) - return super(ListFooOld, self).take_action(parsed_args) -- cgit v1.2.1