Docs: Added shell command for determining pyswbem version

The command was found to be needed, because the `pywbem.__version__`
attribute was added only in pywbem 0.8.1, and the 0.7.0 version
is widely deployed.

The algorithm tries the following sources for the version, in order:
- The value of the `pywbem.__version__` attribute
- Otherwise, the output of the `setup.py --version` command. This is used
  for versions earlier than 0.8.1 that are installed using Python pip
  or easy_install, and it depends on the setup.py file being installed as
  well.
- Otherwise, the version defaults to 0.7.0. This is used when Linux
  distributions have packaged pywbem, without adding its setup.py.

Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>

docs/changes.rst

@@ -140,7 +140,10 @@ Released: not yet
   0.30.1 is now used on Windows, and no longer the somewhat aged versions in
   the `M2CryptoWin32/64` packages. For details, see the installation section
   in the documentation.
-
+
+* Docs: Added a shell command for determining the version of an installed
+  pywbem package, that covers all released pywbem versions (Issue #1246).
+
 **Cleanup**
 
 * Moved class `NocaseDict` into its own module (Issue #848).

docs/intro.rst

@@ -579,15 +579,32 @@ follows:
 Package version
 ---------------
 
-The version of the pywbem package can be accessed by programs using the
-``pywbem.__version__`` variable:
+Since pywbem 0.8.1, the version of the pywbem package can be accessed by
+programs using the ``pywbem.__version__`` variable:
 
 .. autodata:: pywbem._version.__version__
 
 Note: For tooling reasons, the variable is shown as
 ``pywbem._version.__version__``, but it should be used as
 ``pywbem.__version__``.
 
+From earlier versions of pywbem, pywbem 0.7.0 was the only version released to
+Pypi, and most likely also the only version that was packaged as an operating
+system package into Linux distributions.
+
+The following shell command can be used to determine the version of pywbem, for
+all versions that were released to Pypi, and independently of whether pywbem
+was installed as an operating system package or as a Python package::
+
+    python -c "\
+    import pywbem, os, subprocess; \
+    fs=os.path.join(os.path.dirname(pywbem.__file__),'setup.py'); \
+    vs=subprocess.check_output(['python',fs,'--version']).strip() \
+    if os.path.exists(fs) else None; \
+    v=getattr(pywbem, '__version__', vs if vs else '0.7.0-assumed'); \
+    print(v) \
+    "
+
 
 .. _`Standards conformance`: