[openlmi-tools] update documentation
Peter Hatina
phatina at fedoraproject.org
Mon Dec 9 11:41:23 UTC 2013
commit 96512df70b287139aee77fc4df9823cac222d676
Author: Peter Hatina <phatina at redhat.com>
Date: Mon Dec 9 12:40:02 2013 +0100
update documentation
openlmi-tools-11-update-documentation.patch | 367 +++++++++++++++++++++++++++
openlmi-tools.spec | 7 +-
2 files changed, 373 insertions(+), 1 deletions(-)
---
diff --git a/openlmi-tools-11-update-documentation.patch b/openlmi-tools-11-update-documentation.patch
new file mode 100644
index 0000000..1062ef1
--- /dev/null
+++ b/openlmi-tools-11-update-documentation.patch
@@ -0,0 +1,367 @@
+diff --git a/doc/src/associated_objects.rst b/doc/src/associated_objects.rst
+index 570a32d..1e33c89 100644
+--- a/doc/src/associated_objects.rst
++++ b/doc/src/associated_objects.rst
+@@ -55,7 +55,7 @@ object, run following:
+ the returned object shall match the value of this parameter. Default value is
+ `None`.
+
+- Other parameters reffer to:
++ Other parameters refer to:
+
+ * ``IncludeQualifiers`` -- Bool flag indicating, if all qualifiers for each
+ object (including qualifiers on the object and on any returned properties)
+diff --git a/doc/src/classes.rst b/doc/src/classes.rst
+index 5a56aad..c11f139 100644
+--- a/doc/src/classes.rst
++++ b/doc/src/classes.rst
+@@ -132,8 +132,7 @@ See the next example:
+ Creating a new instance
+ ^^^^^^^^^^^^^^^^^^^^^^^
+ LMIShell is able to create an object of specific class, if the provider support
+-this operation. The next example shows, how to add a specific user account to
+-the desired group.
++this operation.
+
+ See the following example:
+
+@@ -208,14 +207,15 @@ Useful Properties
+ -----------------
+ Following part describes few useful :py:class:`LMIClass` properties.
+
+-Class name
++Class Name
+ ^^^^^^^^^^
+ Every class object can return a name of the CIM class, see following:
+
+ .. code-block:: python
+
+ > cls.classname
+- 'ClassName'
++ ClassName
++ >
+
+ Namespace
+ ^^^^^^^^^
+@@ -225,7 +225,28 @@ corresponding namespace for each class, run following:
+ .. code-block:: python
+
+ > cls.namespace
+- 'NamespaceOfClassName'
++ Namespace
++ >
++
++Connection Object
++^^^^^^^^^^^^^^^^^
++This property returns a connection object, which was used to retrieve the
++class (refer to :ref:`startup_connection`). See next example:
++
++.. code-block:: python
++
++ > cls.connection
++ LMIConnection(URI='uri', user='user'...)
++ >
++
++Wrapped Object
++^^^^^^^^^^^^^^
++This property returns a wrapped :py:mod:`pywbem` object. See the example:
++
++.. code-block:: python
++
++ > instance.wrapped_object
++ CIMClass(u'ClassName', ...)
+ >
+
+ Documentation
+diff --git a/doc/src/index.rst b/doc/src/index.rst
+index da23cf4..e598cae 100644
+--- a/doc/src/index.rst
++++ b/doc/src/index.rst
+@@ -3,38 +3,54 @@ OpenLMI Tools documentation
+ `OpenLMI Tools` currently consist of *LMIShell* and the content of the
+ documentation itself is devoted to the LMIShell.
+
+-LMIShell provides a (non)interactive or interactive way how to access CIM
+-objects provided by *OpenPegasus* or *sblim-sfcb* broker.
++LMIShell
++--------
+
+ .. only:: html
+
+- Contents:
++ LMIShell provides a (non)interactive way how to access CIM objects provided
++ by *OpenPegasus* or *sblim-sfcb* broker. The shell is based on a python
++ interpreter and added logic, therefore what you can do in pure python, it is
++ possible in LMIShell. There are classes added to manipulate with CIM
++ classes, instance names, instances, etc. Additional classes are added to
++ fulfill wrapper pattern and expose only those methods, which are necessary
++ for the purpose of a shell.
+
+-
+-.. only:: man
++ **Contents:**
+
+ .. toctree::
++ :maxdepth: 1
++
++ startup
++ namespaces
++ classes
++ instances
++ instance_names
++ associated_objects
++ association_objects
++ indications
++ return_values
++ interactive_interface
++ builtins
++ code
+
+- man_page
+-
+-.. toctree::
+- :maxdepth: 1
++.. only:: man
+
+- structure
+- startup
+- namespaces
+- classes
+- instances
+- instance_names
+- associated_objects
+- association_objects
+- indications
+- return_values
+- interactive_interface
+- builtins
++ LMIShell provides a (non)interactive way how to access CIM objects provided
++ by *OpenPegasus* or *sblim-sfcb* broker.
+
+-.. only:: html
++ .. toctree::
+
+- .. toctree:: :maxdepth: 1
++ man_page
++ startup
++ namespaces
++ classes
++ instances
++ instance_names
++ associated_objects
++ association_objects
++ indications
++ return_values
++ interactive_interface
++ builtins
+
+- code
+diff --git a/doc/src/instance_names.rst b/doc/src/instance_names.rst
+index ec2fc0d..ec0c2cf 100644
+--- a/doc/src/instance_names.rst
++++ b/doc/src/instance_names.rst
+@@ -36,21 +36,55 @@ Useful Properties
+
+ Following part describes :py:class:`LMIInstanceName` useful properties.
+
+-Class name
++Class Name
+ ^^^^^^^^^^
+-To get a class name of the instance name, execute:
++The property returns a string representation of the class name. See next
++example:
+
+ .. code-block:: python
+
+ > instance_name.classname
++ ClassName
+ >
+
+-Path
+-^^^^
+-To get a path string from the instance name, execute following:
++Namespace
++^^^^^^^^^
++The property returns a string representation of namesapce. See next example:
+
+ .. code-block:: python
+
+- > instance_name.path
+- ...
++ > instance_name.namespace
++ Namespace
++ >
++
++Host Name
++^^^^^^^^^
++This property returns a string representation of the host name, where the CIM
++instance is located.
++
++.. code-block:: python
++
++ > instance_name.hostname
++ Hostname
++ >
++
++Connection Object
++^^^^^^^^^^^^^^^^^
++This property returns a connection object, which was used to retrieve the
++instance name (refer to :ref:`startup_connection`). See next example:
++
++.. code-block:: python
++
++ > instance.connection
++ LMIConnection(URI='uri', user='user'...)
++ >
++
++Wrapped Object
++^^^^^^^^^^^^^^
++This property returns a wrapped :py:mod:`pywbem` object. See the example:
++
++.. code-block:: python
++
++ > instance.wrapped_object
++ CIMInstanceName(classname=u'ClassName', keybindings=NocaseDict(...), host=u'hostname', namespace='namespace')
+ >
+diff --git a/doc/src/instances.rst b/doc/src/instances.rst
+index 771c27e..7ca285a 100644
+--- a/doc/src/instances.rst
++++ b/doc/src/instances.rst
+@@ -39,8 +39,8 @@ To execute a method within an object, run this:
+ )
+ >
+
+-**NOTE:** Method parameters are passed in a dictionary, as seen in the previous
+-example.
++**NOTE:** Instances **do not** auto-refresh after a method calls. It is
++necessary to perform this operation by hand (See :ref:`instances_refreshing`).
+
+ To get the result from a method call, see following:
+
+@@ -65,6 +65,7 @@ classes:
+
+ * :py:class:`LMI_StorageJob`
+ * :py:class:`LMI_SoftwareInstallationJob`
++* :py:class:`LMI_SoftwareVerificationJob`
+ * :py:class:`LMI_NetworkJob`
+
+ LMIShell first tries to use indications as the waiting method. If it fails,
+@@ -79,7 +80,7 @@ Following example illustrates, how to perform a synchronous method call:
+ ... "Param2" : value2, ...})
+ >
+
+-**NOTE:** See the prefix ``Sync`` of a method name.
++**NOTE:** See the prefix `Sync` of a method name.
+
+ When a synchronous method call is done:
+
+@@ -231,6 +232,14 @@ A single instance can be removed from the CIMOM by executing:
+ **NOTE:** After executing the :py:meth:`.LMIInstance.delete` method, all the
+ object properties, methods will become inaccessible.
+
++Deletion of the instance can be verified by:
++
++.. code-block:: python
++
++ > instance.is_deleted
++ True
++ >
++
+ Documentation
+ -------------
+ For an instance object, you can also use a documentation method, which will
+@@ -260,7 +269,7 @@ Useful Properties
+ -----------------
+ Following part describes :py:class:`LMIInstance` useful properties.
+
+-Class name
++Class Name
+ ^^^^^^^^^^
+ Each instance object provide a property, that returns its class name. To get a
+ string of the class name, run following:
+@@ -268,6 +277,7 @@ string of the class name, run following:
+ .. code-block:: python
+
+ > instance.classname
++ ClassName
+ >
+
+ Namespace
+@@ -278,18 +288,37 @@ To get a string of the namespace name, run following:
+ .. code-block:: python
+
+ > instance.namespace
+- 'root/cimv2'
++ Namespace
+ >
+
+ Path
+ ^^^^
+-To retrieve a unique identification object for an instance,
+-:py:class:`CIMNamespaceName`, execute following:
++To retrieve a unique, wrapped, identification object for the instance,
++:py:class:`LMIInstanceName`, execute following:
+
+ .. code-block:: python
+
+ > instance.path
+- namespace:ClassName.CreationClassName="CreationClassName", \
+- SystemName="SystemName",Name="InstanceName", \
+- SystemCreationClassName="SystemCreationClassName"
++ LMIInstanceName(classname="ClassName"...)
++ >
++
++Connection Object
++^^^^^^^^^^^^^^^^^
++This property returns a connection object, which was used to retrieve the
++instance (refer to :ref:`startup_connection`). See next example:
++
++.. code-block:: python
++
++ > instance.connection
++ LMIConnection(URI='uri', user='user'...)
++ >
++
++Wrapped Object
++^^^^^^^^^^^^^^
++This property returns a wrapped :py:mod:`pywbem` object. See the example:
++
++.. code-block:: python
++
++ > instance.wrapped_object
++ CIMInstance(classname=u'ClassName', ...)
+ >
+diff --git a/doc/src/startup.rst b/doc/src/startup.rst
+index 307eb37..eae1732 100644
+--- a/doc/src/startup.rst
++++ b/doc/src/startup.rst
+@@ -75,20 +75,28 @@ See following example:
+ Credentials validation
+ ^^^^^^^^^^^^^^^^^^^^^^
+ Function :py:func:`.connect` returns either :py:class:`LMIConnection` object, if
+-provided credentials are OK, otherwise ``None`` is returned:
++the connection can be established, otherwise ``None`` is returned. Suppose, the
++LMIShell is run in verbose mode (:option:`-v`, :option:`--verbose`, :option:`-m`
++or :option:`--more-verbose` is used). See following example of creating a connection:
+
+ .. code-block:: python
+
+ > # correct username or password
+ > c = connect("host", "username", "password")
++ INFO: Connected to host
+ > isinstance(c, LMIConnection)
+ True
+ > # wrong login username or password
+ > c = connect("host", "wrong_username", "wrong_password")
++ ERROR: Error connecting to host, <error message>
+ > c is None
+ True
+ >
+
++**NOTE:** By default, LMIShell prints out only error messages, when calling a
++:py:func:`.connect`; no INFO messages will be print out. It is possible to
++suppress all the messages by passing :option:`-q` or :option:`--quiet`).
++
+ Server's certificate validation
+ -------------------------------
+ When using https transport protocol, LMIShell tries to validate each
diff --git a/openlmi-tools.spec b/openlmi-tools.spec
index bceb492..ff21c85 100644
--- a/openlmi-tools.spec
+++ b/openlmi-tools.spec
@@ -1,6 +1,6 @@
Name: openlmi-tools
Version: 0.9
-Release: 11%{?dist}
+Release: 12%{?dist}
Summary: Set of CLI tools for Openlmi providers
License: GPLv2+
@@ -16,6 +16,7 @@ Patch6: openlmi-tools-07-fix-interactive-connect.patch
Patch7: openlmi-tools-08-fix-compulsory-call-order-listener.patch
Patch8: openlmi-tools-09-fix-blocking-when-receiving-indication.patch
Patch9: openlmi-tools-10-fix-indication-unique-name.patch
+Patch10: openlmi-tools-11-update-documentation.patch
BuildArch: noarch
BuildRequires: automake
@@ -53,6 +54,7 @@ Summary: Documentation for %{name}
%patch7 -p1
%patch8 -p1
%patch9 -p1
+%patch10 -p1
%build
pushd cli
@@ -104,6 +106,9 @@ install -m 644 cli/completion/_lmishell $zsh_comp_dir
%{_docdir}/%{name}-%{version}/html
%changelog
+* Mon Dec 9 2013 Peter Hatina <phatina at redhat.com> - 0.9-12
+- update documentation
+
* Fri Dec 6 2013 Peter Hatina <phatina at redhat.com> - 0.9-11
- fix indication unique name
More information about the scm-commits
mailing list