documentation fixes

Lot of corrections, typo fixes. Added some cross-references.

Added automatically generated documentaion from sources.
Added gendoc.sh script, that generates rst files for modules.

8 files changed, 349 insertions, 104 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 387690e..55f5b05 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -10,12 +10,14 @@ BUILDDIR      = _build
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -n -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext mof generated
 
+all: html
+
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
@@ -38,8 +40,14 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
+api.rst: gendoc.sh $(wildcard ../lmi/scripts/*.py \
+	    ../lmi/scripts/common/*.py \
+	    ../lmi/scripts/_metacommand/*.py \
+	    ../lmi/scripts/formatter/*.py)
+	./gendoc.sh
+
 clean:
-	-rm -rf $(BUILDDIR)/*
+	-rm -rf $(BUILDDIR)/* modules/ api.rst
 
 %.png: %.dia
 	dia -e $@ $<
@@ -50,7 +58,7 @@ clean:
 figures:
 
 
-html: figures
+html: figures api.rst
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
diff --git a/doc/command-classes.rst b/doc/command-classes.rst
index 07575dd..82dbe03 100644
--- a/doc/command-classes.rst
+++ b/doc/command-classes.rst
@@ -9,6 +9,9 @@ We focus here on commands intended for subclassing in command wrapper modules.
 *OpenLMI Scripts* defines and uses other kinds of commands internally. But
 the script developer does not need to know about them.
 
+.. seealso::
+    General and class specific properties in :ref:`command_properties`.
+
 .. _end-point_commands:
 
 End-point commands
@@ -25,7 +28,7 @@ methods:
     Properties affecting this pre-processing can be found in
     :ref:`pre_processing_properties`. This method shall check option values or
     their combination and raise ``lmi.scripts.common.errors.LmiInvalidOptions``
-    if any inconsistency discovered.
+    if any inconsistency is discovered.
 
     Example usage: ::
 
@@ -41,8 +44,12 @@ methods:
                             'invalid file type given, must be one of %s' %
                                  file_types)
 
+    .. seealso::
+        API doccumentation on
+        :py:meth:`lmi.scripts.common.command.command.LmiEndPointCommand.verify_options`
+
 ``transform_options(self, options)``
-    Taking verified options dictionary. It modifies this dictionary in
+    Takes verified options dictionary. It modifies this dictionary in
     arbitrary way in place. Its return value is ignored.
 
     Example usage: ::
@@ -57,11 +64,15 @@ methods:
                 """
                 options['<devices>'] = options.pop('<device>')
 
-Above methods can be used to process options in a way, that any script library
-function can be called. In a case we need more control over what is called or
-when we want to decide at runtime which function shall be call, we may override
-``execute()`` method instead. Example of this may be found at
-:ref:`associating_a_function`.
+    .. seealso::
+        API documentation on
+        :py:meth:`lmi.scripts.common.command.command.LmiEndPointCommand.transform_options`
+
+Above methods can be used to process options in a way that any script library
+function can be called. In case we need more control over what is called or
+when we want to decide at runtime which function shall be called, we may override
+:py:meth:`lmi.scripts.common.command.command.LmiEndPointCommand.execute` method
+instead. Example of this may be found at :ref:`associating_a_function`.
 
 .. _lmi_check_result:
 
@@ -77,11 +88,15 @@ such as ``LMI_Service::StartService()``. Example can be seen in
 
 Its specific properties are listed in :ref:`lmi_check_result_properties`.
 
+.. seealso::
+    API documentation on
+    :py:class:`lmi.scripts.common.command.command.LmiCheckResult`
+
 .. _lmi_lister:
 
 ``LmiLister``
 ~~~~~~~~~~~~~
-Prints a table like data. It expects associated function to return its result
+Prints tablelike data. It expects associated function to return its result
 in form: ::
 
     [row1, row2, ...]
@@ -97,6 +112,10 @@ take the following form instead: ::
 Where ``columns`` has the same meaning as ``COLUMNS`` as a class property and
 ``data`` is the result of previous case [#]_.
 
+.. seealso::
+    API documentation on
+    :py:class:`lmi.scripts.common.command.command.LmiLister`
+
 .. _lmi_instance_lister:
 
 ``LmiInstanceLister``
@@ -104,7 +123,7 @@ Where ``columns`` has the same meaning as ``COLUMNS`` as a class property and
 Is a variant of ``LmiLister``. Instead of rows being tuples, here they are
 instances of some CIM class. Instead of using ``COLUMNS`` property for
 specifying columns labels, ``PROPERTIES`` is used for the same purpose here.
-Its primary use is in specifying, which properties of instances shall be
+Its primary use is in specifying which properties of instances shall be
 rendered in which column. This is described in detail in
 :ref:`lmi_instance_lister_properties`.
 
@@ -114,18 +133,22 @@ The expected output of associated function is therefore: ::
 
 Again, usage of generators is preferred.
 
+.. seealso::
+    API documentation on
+    :py:class:`lmi.scripts.common.command.command.LmiInstanceLister`
+
 .. _lmi_show_instance:
 
 ``LmiShowInstance``
 ~~~~~~~~~~~~~~~~~~~
 Renders a single instance of some CIM class. It's rendered in a form of
-two-column table. Where the first column contains property names and
+two-column table, where the first column contains property names and
 the second their corresponding values. Rendering is controlled in the same
 way as for ``LmiInstanceLister`` (see :ref:`lmi_show_instance_properties`).
 
 .. seealso::
-
-    General and class specific properties in :ref:`command_properties`.
+    API documentation on
+    :py:class:`lmi.scripts.common.command.command.LmiShowInstance`
 
 .. ****************************************************************************
 
@@ -136,5 +159,5 @@ way as for ``LmiInstanceLister`` (see :ref:`lmi_show_instance_properties`).
 
 -------------------------------------------------------------------------------
 
-.. [#] Having the same lenght as each row in returned data.
+.. [#] Having the same length as each row in returned data.
 .. [#] Generator or a ``list`` of rows.
diff --git a/doc/command-properties.rst b/doc/command-properties.rst
index cad41dd..bc13e5a 100644
--- a/doc/command-properties.rst
+++ b/doc/command-properties.rst
@@ -34,7 +34,7 @@ example looks like this: ::
 
 Values of this dictionary are passed to an associated function as arguments
 with names created out of matching keys. Since argument names can not contain
-characters such as `'<'`, `'>'`, `'-'`, etc. These need to be replaced.
+characters such as `'<'`, `'>'`, `'-'`, etc., these need to be replaced.
 Process of renaming of these options can be described by the following pseudo
 algorithm:
 
@@ -55,7 +55,7 @@ algorithm:
         "-a"    -> "_a"
         "--all" -> "_all"
 
-    4. any not-empty sequence of characters not allowed in python's identitier
+    4. any non-empty sequence of characters not allowed in python's identitier
        shall be replaced with a single underscore ::
 
         "_long-option"     -> "_long_option"
@@ -83,7 +83,7 @@ Property descriptions
 
 ``ARG_ARRAY_SUFFIX`` : ``str`` (defaults to ``""``)
     Adds additional point (5) to `options_transform_algorithm`_. All
-    repeatable arguments, resulting in a ``list`` of items are renamed to
+    repeatable arguments, resulting in a ``list`` of items, are renamed to
     ``<original_name><suffix>`` [#]_. Repeatable argument in usage string
     looks like this: ::
 
@@ -97,7 +97,7 @@ Property descriptions
 .. _own_usage:
 
 ``OWN_USAGE`` : ``bool`` (defaults to ``False``)
-    Says, whether the documentation string of this class is a usage string.
+    Says whether the documentation string of this class is a usage string.
     Each command in hierarchy can have its own usage string.
 
     This can also be assigned a usage string directly: ::
@@ -138,10 +138,11 @@ Influencing properties:
 
     * ``CALLABLE`` (callable_)
 
-When command is invoked, it's method ``execute()`` will get verified and
-transformed options as a positional and keyword arguments. This method
-shall pass them to an associated function residing in script library and
-return its result on completition.
+When command is invoked, its method
+:py:meth:`lmi.scripts.common.command.command.LmiEndPointCommand.execute` will
+get verified and transformed options as positional and keyword arguments.
+This method shall pass them to an associated function residing in script
+library and return its result on completition.
 
 One way to associate a function is to use ``CALLABLE`` property. The other
 is to define very own ``execute()`` method like this: ::
@@ -160,9 +161,8 @@ is to define very own ``execute()`` method like this: ::
             for service_inst in service.list_services(ns, kind):
                 yield service_inst
 
-This approach allows to access properties of command and application allowing
-for more advanced approaches to options handling, verifying and result
-post-processing.
+This may come handy if the application object [#]_ needs to be accessed or
+if we need to decide which function to call based on command line options.
 
 .. _property_descriptions:
 
@@ -171,9 +171,10 @@ Property descriptions
 .. _callable:
 
 ``CALLABLE`` : ``str`` (defaults to ``None``)
-    This is a mandatory option if ``execute()`` method is not overriden.
-    It may be a string composed of a full path of module and its callable
-    delimited with ``':'``: ::
+    This is a mandatory option if
+    :py:meth:`lmi.scripts.common.command.command.LmiEndPointCommand.execute`
+    method is not overriden. It may be a string composed of a full path of
+    module and its callable delimited with ``':'``: ::
 
         CALLABLE = 'lmi.scripts.service:start'
 
@@ -187,11 +188,11 @@ Property descriptions
             CALLABLE = service.start
             EXPECT = 0
 
-    The first variant (by assigning string) comes handy, if the particular
+    The first variant (by assigning string) comes handy if the particular
     module of associated function is not yet imported. Thus delaying the
     import until the point of function's invocation - if the execution comes
     to this point at all. In short it speeds up execution of ``lmi``
-    meta-command by reducing number of module imports, that are not needed.
+    meta-command by reducing number of module imports that are not needed.
 
 .. _function_invocation:
 
@@ -210,19 +211,19 @@ Property descriptions
     This property affects the first argument passed to an associated function.
     Various values have different impact:
 
-    +-----------+---------------------------------------+-------------------+
-    | Value     | Value of first argument.              | Its type          |
-    +===========+=======================================+===================+
-    | ``None``  | Same impact as value ``"root/cimv2"`` | ``LMINamespace``  |
-    +-----------+---------------------------------------+-------------------+
-    | ``False`` | Raw connection object                 | ``LMIConnection`` |
-    +-----------+---------------------------------------+-------------------+
-    | any path  | Namespace object with given path      | ``LMINamespace``  |
-    +-----------+---------------------------------------+-------------------+
+    +-----------+---------------------------------------+-------------------------------------+
+    | Value     | Value of first argument.              | Its type                            |
+    +===========+=======================================+=====================================+
+    | ``None``  | Same impact as value ``"root/cimv2"`` | :py:class:`lmi.shell.LMINamespace`  |
+    +-----------+---------------------------------------+-------------------------------------+
+    | ``False`` | Raw connection object                 | :py:class:`lmi.shell.LMIConnection` |
+    +-----------+---------------------------------------+-------------------------------------+
+    | any path  | Namespace object with given path      | :py:class:`lmi.shell.LMINamespace`  |
+    +-----------+---------------------------------------+-------------------------------------+
 
     This usually won't need any modification. Sometimes perhaps associated
-    function might want to access more than one namespace, in that case
-    an instance of ``LMIConnection`` might provide more useful.
+    function might want to access more than one namespace, in that case an
+    instance of :py:class:`lmi.shell.LMIConnection` might provide more useful.
 
     Namespace can also be overriden globally in a configuration file or with
     an option on command line.
@@ -252,8 +253,10 @@ them.
     Where ``Subcmd1`` and ``Subcmd2`` are some other ``LmiBaseCommand``
     subclasses. Documentation string must be parseable with docopt_.
 
-    ``COMMANDS`` property will be translated to ``child_commands()`` class
-    method by ``lmi.scripts.common.command.meta.MultiplexerMetaClass``.
+    ``COMMANDS`` property will be translated to
+    :py:meth:`lmi.scripts.common.command.command.LmiCommandMultiplexer.child_commands`
+    class method by
+    :py:class:`lmi.scripts.common.command.meta.MultiplexerMetaClass`.
 
 .. _lmi_lister_properties:
 
@@ -265,7 +268,9 @@ them.
     Column names. It's a tuple with name for each column. Each row of data
     shall then contain the same number of items as this tuple. If omitted,
     associated function is expected to provide them in the first row of
-    returned list. It's translated to ``get_columns()`` class method.
+    returned list. It's translated to
+    :py:meth:`lmi.scripts.common.command.command.LmiBaseListerCommand.get_columns`
+    class method.
 
 .. _lmi_instance_commands_properties:
 .. _lmi_show_instance_properties:
@@ -273,9 +278,9 @@ them.
 
 ``LmiShowInstance`` and ``LmiInstanceLister`` properties
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-These two classes expect as a result of their associated function an instance
+These two classes expect, as a result of their associated function, an instance
 or a list of instances of some CIM class. They take care of rendering them to
-standard output. Thus their properties affect the way, how their properties
+standard output. Thus their properties affect the way how their properties
 are rendered. 
 
 .. _properties:
@@ -310,7 +315,7 @@ are rendered.
                     ('Active', 'Started'))
 
     First property will be shown with the same label as the name of property.
-    Second one modifies the value of ``EnabledDefault`` from integer to
+    Second one modifies the value of ``EnabledDefault`` from ``int`` to
     ``bool`` representing enabled state. The last one uses different label for
     property name ``Started``.
 
@@ -325,8 +330,13 @@ are rendered.
     Where ``properties`` have the same inscription and meaning as a
     ``PROPERTIES`` property of class.
 
-    Otherwise only the ``data`` is expexted which has different meaning
-    for ``LmiShowInstance`` and ``LmiInstanceLister``.
+    Otherwise, only the ``data`` is expected.
+
+    .. note::
+        Both :py:class:`lmi.scripts.common.command.command.LmiShowInstance`
+        and :py:class:`lmi.scripts.common.command.command.LmiInstanceLister`
+        expect different ``data`` to be returned. See :ref:`lmi_show_instance`
+        and :ref:`lmi_instance_lister` for more information.
 
 .. note::
 
@@ -342,7 +352,7 @@ are rendered.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 This command typically does not produce any output if operation succeeds.
 The operation succeeds if the result of associated function is
-expected. There are more ways, how to say, what is an expected result.
+expected. There are more ways how to say what is an expected result.
 One way is to use ``EXPECT`` property. The other is to provide very own
 definition of ``check_result()`` method.
 
@@ -357,7 +367,8 @@ definition of ``check_result()`` method.
     accept exactly two parameters:
 
         1. options - Dictionary with parsed command line options returned by
-           docopt_ after being processed by ``transform_options()``.
+           docopt_ after being processed by
+           :py:meth:`lmi.scripts.common.command.command.LmiEndPointCommand.transform_options`.
         2. result - Return value of associated function.
 
 .. seealso::
@@ -368,6 +379,7 @@ definition of ``check_result()`` method.
 
 .. [#] Angle brackets here just mark the boundaries of name components. They
        have nothing to do with arguments.
+.. [#] Application object is accessible through ``app`` property of each command instance.
 
 .. ****************************************************************************
 
diff --git a/doc/conf.py b/doc/conf.py
index 787394c..7dfd8ae 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -16,7 +16,7 @@ import sys, os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../lmi'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -25,7 +25,7 @@ import sys, os
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.todo', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -183,7 +183,7 @@ latex_elements = {
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index_new', 'OpenLMIScripts.tex', u'OpenLMI Scripts Documentation',
+  ('index', 'OpenLMIScripts.tex', u'OpenLMI Scripts Documentation',
    u'Michal Minář', 'manual'),
 ]
 
@@ -213,7 +213,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index_new', 'openlmiscripts', u'OpenLMI Scripts Documentation',
+    ('index', 'openlmiscripts', u'OpenLMI Scripts Documentation',
      [u'Michal Minář'], 1)
 ]
 
@@ -227,7 +227,7 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index_new', 'OpenLMIScripts', u'OpenLMI Scripts Documentation',
+  ('index', 'OpenLMIScripts', u'OpenLMI Scripts Documentation',
    u'Michal Minář', 'OpenLMIScripts', 'One line description of project.',
    'Miscellaneous'),
 ]
diff --git a/doc/configuration.rst b/doc/configuration.rst
new file mode 100644
index 0000000..a538415
--- /dev/null
+++ b/doc/configuration.rst
@@ -0,0 +1,131 @@
+.. _configuration:
+
+Configuration
+=============
+``lmi`` meta-command has the main configuration file located in: ::
+
+    /etc/openlmi/scripts/lmi.conf
+
+User can have his own configuration file overriding anything in global one above: ::
+    
+    $HOME/.lmirc
+
+Configuration is written in MS Windows INI files fashion. Please refer to
+corresponding `RFC 822`_ and to `ConfigParser`_ for python specific
+interpretation language.
+
+Follows a list of sections with their list of options. Most of the options
+listed here can be overriden with command line parameters.
+
+.. seealso::
+    :py:mod:`lmi.scripts.common.configuration`
+
+Section [Main]
+--------------
+.. _main_command_namespace:
+
+CommandNamespace : ``string``
+    Python namespace, where command entry points will be searched for.
+
+    Defaults to ``lmi.scripts.cmd``.
+
+.. _main_trace:
+
+Trace : ``boolean``
+    Whether the exceptions should be logged with tracebacks.
+
+    Defaults to ``False``.
+
+.. _main_verbosity:
+
+Verbosity: ``integer``
+    A number within 0-2 range saying, how verbosive the output
+    shall be. This differs from `log_level`_, which controls the logging
+    messages. This option is recognized by commands alone making them
+    print more information on stdout.
+
+    Defaults to 0.
+
+Section [CIM]
+-------------
+.. _cim_namespace:
+
+Namespace : ``string``
+    Allows to override default CIM namespace, which will be passed to
+    script library functions.
+
+    Defaults to ``root/cimv2``.
+
+Section [SSL]
+-------------
+.. _ssl_verify_server_certificate:
+
+VerifyServerCertificate : ``boolean``
+    Whether to verify server-side certificate, when making secured
+    connection over https.
+
+    Defaults to ``True``.
+
+
+Section [Format]
+----------------
+.. _format_human_friendly:
+
+HumanFriendly : ``boolean``
+    Whether to print values in human readable forms (e.g. with units).
+
+    Defaults to ``False``.
+
+.. _format_lister_format:
+
+ListerFormat : one of {``csv``, ``table``}
+    What format to use, when listing tabular data. ``csv`` format allows for
+    easy machine parsing, the second one is more human friendly.
+
+    Defaults to ``table``.
+
+.. _format_no_headings:
+
+NoHeadings : ``boolean``
+    Whether to suppress headings (column names) when printing tables.
+
+    Defaults to ``False``.
+
+Section [Log]
+-------------
+.. _log_level:
+
+Level : one of {``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``}
+    Minimal serverity level of messages to log. Affects only logging to a
+    file.
+
+    Defaults to ``ERROR``.
+
+.. _log_console_format:
+
+ConsoleFormat : ``string``
+    Format string used when logging to a console. 
+
+    Defaults to ``%(levelname)s: %(message)s``.
+
+.. _log_file_format:
+
+FileFormat : ``string``
+    Format string used, when logging to a console. This applies only when
+    *OutputFile* is set (see below).
+
+    Defaults to 
+        ``%(asctime)s:%(levelname)-8s:%(name)s:%(lineno)d - %(message)s``
+
+.. _log_output_file:
+
+OutputFile : ``string``
+    Allows to set a path to file, where messages will be logged. No log
+    file is written at default.
+
+    Defaults to empty string.
+
+.. ****************************************************************************
+
+.. _`RFC 822`: http://tools.ietf.org/html/rfc822.html
+.. _`ConfigParser`:        http://docs.python.org/2/library/configparser.html
diff --git a/doc/gendoc.sh b/doc/gendoc.sh
new file mode 100755
index 0000000..8803413
--- /dev/null
+++ b/doc/gendoc.sh
@@ -0,0 +1,59 @@
+#!/bin/bash
+
+#
+# Helper script to generate developer documentation in
+# doc/devel/modules and index.rst
+#
+
+TOPDIR=..
+
+[ -e $TOPDIR/doc/modules ] || mkdir $TOPDIR/doc/modules
+
+function get_modules() {
+    find $TOPDIR/lmi/scripts/ -type f -a -name '*.py' | \
+        sed 's:/__init__\.py$::' | \
+        grep -v "^${TOPDIR}/lmi/scripts/\?$" | \
+        grep -v '/_' | \
+        sort -u
+}
+
+function get_module_name() {
+    path=`sed -e "s:^.*${TOPDIR}/lmi/scripts/\(.*\)$:\1:" -e "s:/:.:g"`
+    basename -s .py "$path"
+}
+
+# api.rst header
+cat >$TOPDIR/doc/api.rst <<_EOF_
+OpenLMI Scripts API
+===================
+
+This is a generated documentation form *OpenLMI Scripts* sources.
+
+Developer of script library will be interested in
+:py:mod:\`lmi.scripts.common\` package providing useful functionality to
+script development.
+
+Contents:
+
+.. toctree::
+    :maxdepth: 2
+
+_EOF_
+
+# Generate modules/*.rst
+for module_path in `get_modules`; do
+    module=`echo "$module_path" | get_module_name`
+    out=$module.rst
+    len=`echo $module| wc -c`
+    len=$(($len-1))
+    underline=""
+    for i in `seq $len`; do underline="=$underline"; done
+
+    cat >$TOPDIR/doc/modules/$out  <<_EOF_
+$module
+$underline
+.. automodule:: lmi.scripts.$module
+    :members:
+_EOF_
+    echo >>$TOPDIR/doc/api.rst "    modules/$module"
+done
diff --git a/doc/index.rst b/doc/index.rst
index 4dbeffc..aeb1517 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -14,3 +14,11 @@ Content:
     usage
     configuration
     script-development
+    api
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc/script-development.rst b/doc/script-development.rst
index 5298208..4c87428 100644
--- a/doc/script-development.rst
+++ b/doc/script-development.rst
@@ -10,21 +10,21 @@ have a general idea about, what OpenLMI_ is and what it does. He should get
 familiar with ``lmishell``, which is a python binary shipped with
 openlmi-tools_.
 
-Also user should be acquinted in writing unix's command line utilities help
-strings [#]_.
+Also user should be acquinted with writing help strings for unix command line
+utilities [#]_.
 
 Introduction
 ------------
 By a *script* in this document we mean:
   
-  * Python library exploiting ``lmishell`` for instrumenting CIM providers
+  * Python library utilizing ``lmishell`` for instrumenting CIM providers
     through a CIMOM broker. It resides in ``lmi.scripts.<profile_name>``
     package, where ``<profile_name>`` corresponds to a DMTF profile or an
     arbitrary set of ``OpenLMI`` providers.
   * Command wrappers for this library as a set of classes inheriting from
-    ``lmi.scripts.common.command.base.LmiBaseCommand``. These may create a
-    hierarchy of nested subcommands. They are the entry points of ``lmi``
-    meta-command to the wrapped functionality of library.
+    :py:class:`lmi.scripts.common.command.base.LmiBaseCommand`. These may
+    create a hierarchy of nested subcommands. They are the entry points of
+    ``lmi`` meta-command to the wrapped functionality of library.
 
 Command wrappers are part of the library usually grouped in a single
 module named after the ``lmi`` subcommand or ``cmd``: ::
@@ -45,11 +45,11 @@ represent possible use cases of what can be done with particular
 providers instead of wrapping 1-to-1 a CIM class's methods in python
 functions.
 
-Any function that shall be called by a command wrapper must accect
-a ``namespace`` argument, which by a convention is called as ``ns``.
-It's an instance of ``lmi.shell.LMINamespace`` providing quick access to
+Any function that shall be called by a command wrapper must accect a
+``namespace`` argument, which by a convention is called ``ns``. It's an
+instance of :py:class:`lmi.shell.LMINamespace` providing quick access to
 represented CIM namespace [#]_ and its classes. It's also possible to specify
-that function shall be passed a raw ``lmi.shell.LMIConnection`` object.
+that function shall be passed a raw :py:class:`lmi.shell.LMIConnection` object.
 For details see :ref:`function_invocation`.
 
 Service example
@@ -64,7 +64,7 @@ useful methods such as:
     * ``StartService()``
     * ``StopService()``
 
-We'd like our users to provide a way, how to list system services, get a
+We'd like our users to provide a way how to list system services, get a
 details for one of them and allow to start, stop and restart them.
 
 Simplified [#]_ version of some of these functions may look like this: ::
@@ -86,7 +86,7 @@ Simplified [#]_ version of some of these functions may look like this: ::
 
 It yields instances of ``LMI_Service`` class. There is no need to use
 exclusively ``yield`` statement instead of ``return``. We prefer to use it in
-enumerating functions because of memory usage reduce (which is possible to
+enumerating functions because of memory usage reduction (which is possible to
 occur in the future, when underlying components will also allow for lazy
 evaluation). Moreover user may limit the number of instances listed, reducing
 the number of instances evaluated.
@@ -133,7 +133,7 @@ these functions operating upon a connection object like this: ::
         return inst
 
 User can then easily access any other namespace he may need. Command classes
-need to be informed about, what wrapped function expects. This will be
+need to be informed about what wrapped function expects. This will be
 explained later in more detail (see :ref:`function_invocation`).
 
 The ``LOG`` variable provides acces to the logger of this module. Messages
@@ -141,12 +141,12 @@ logged in this way end up in a log file [#]_ and console. Implicitly only
 warnings and higher priority messages are logged into a console. This is
 controllable with ``lmi`` parameters.
 
-Useful informations should not be rendered or printed by these functions
+Useful information should not be rendered or printed by these functions
 directly. Wrapper commands shall post-process instances or data returned,
 render useful information and print it on standard output stream.
 
 If operation fails due to some not-so-unexpected error, please use
-``lmi.scripts.common.errors.LmiFailed`` exception with human readable
+:py:class:`lmi.scripts.common.errors.LmiFailed` exception with human readable
 description.
 
 For more *real world* examples, take a look on scripts already present in our
@@ -158,7 +158,7 @@ Command wrappers overview
 -------------------------
 They are a set of commands wrapping up library's functionality in a set of
 commands creating a tree invocable by ``lmi`` meta-command. All commands are
-subclasses of ``lmi.scripts.common.command.base.LmiBaseCommand``.
+subclasses of :py:class:`lmi.scripts.common.command.base.LmiBaseCommand`.
 
 Behaviour of commands is controlled by class properties such as these: ::
 
@@ -173,9 +173,9 @@ Behaviour of commands is controlled by class properties such as these: ::
 
 Example above contains definition of **show** command for instances of
 ``LMI_Service``. Its associated function is ``get_instance()`` located in
-``lmi.scripts.service`` module [#]_. Properties used will be described in
-detail later (see :ref:`lmi_instance_commands_properties`). Let's just say,
-that ``PROPERTIES`` specify a way, how the instance is rendered.
+``lmi.scripts.service`` module [#]_. Properties used will be described
+in detail later (see :ref:`lmi_instance_commands_properties`). Let's just say,
+that ``PROPERTIES`` specify a way how the instance is rendered.
 
 Top-level commands
 ~~~~~~~~~~~~~~~~~~
@@ -187,12 +187,12 @@ For example: ::
     $ lmi sw show openlmi-providers
 
 ``help``, ``service`` and ``sw`` are top-level commands. One script library
-(such a ``service`` above) can provide one or more of them. They need to be
+(such as ``service`` above) can provide one or more of them. They need to be
 listed in a ``setup.py`` script in ``entry_points`` argument of ``setup()``
 function. More details will be noted later in `Writing setup.py`_.
 
 They contain usage string which is a documentation and prescription of
-command-line arguments in one string. This string is printed, when user
+command-line arguments in one string. This string is printed when user
 requests command's help: ::
 
     $ lmi help
@@ -253,7 +253,7 @@ following:
     6. collect results
     7. render them and print them
 
-Developper of command wrappers need to be familiar with each step. We will
+Developper of command wrappers needs to be familiar about each step. We will
 describe them later in details.
 
 There are following end-point commands available for subclassing:
@@ -263,8 +263,7 @@ There are following end-point commands available for subclassing:
     * ``LmiInstanceLister`` (see :ref:`lmi_instance_lister`)
     * ``LmiShowInstance``   (see :ref:`lmi_show_instance`)
 
-They differ in a way, how they render the result obtained from associated
-function.
+They differ in how they render the result obtained from associated function.
 
 These are listed in depth in :ref:`end-point_commands`.
 
@@ -272,12 +271,12 @@ These are listed in depth in :ref:`end-point_commands`.
 
 Command multiplexers
 ~~~~~~~~~~~~~~~~~~~~
-Provide a way, how to group multiple commands under one. Suppose you want to
+Provide a way how to group multiple commands under one. Suppose you want to
 list packages, repositories and files. All of these use cases need different
-arguments, and render different informations so logically these they should
-be independent end-point commands. What binds them together is the user's
-wish to *list* something. He may wish for other things like *show*, *add*,
-*remove* etc. Having all combination of these wishes and things would
+arguments, and render different information so logically they should be
+represented by independent end-point commands. What binds them together is the
+user's wish to *list* something. He may wish for other things like *show*,
+*add*, *remove* etc. Having all combination of these wishes and things would
 generate a lot of commands under the top-level one. Let's instead group them
 under particular *wish* like this:
 
@@ -287,7 +286,9 @@ under particular *wish* like this:
     * ``sw show package``
 
 To reflect it in our commands definition hierarchy, we need to use
-``LmiCommandMultiplexer`` command. ::
+:py:class:`lmi.scripts.common.command.command.LmiCommandMultiplexer` command.
+
+::
 
     class Lister(command.LmiCommandMultiplexer):
         """ List information about packages, repositories or files. """
@@ -328,15 +329,16 @@ The top-level command is usally defined like this: ::
 Where the ``__doc__`` is a usage string (see usage_string_) and module's doc
 string at the same time. It's  mentioned in point 2. ``Service`` is a name,
 which will be listed in ``entry_points`` dictionary described in section below
-(entry_points_). The global variable's name we assign to should be the same
-as a value of the first argument to ``register_subcommands()``. The last
-argument here is the dictionary mapping all subcommands of **service** to
-their names [#]_.
+(entry_points_). The global variable's name we assign to should be the same as
+the value of the first argument to
+:py:func:`lmi.scripts.common.command.helper.register_subcommands`. The last
+argument here is the dictionary mapping all subcommands of **service** to their
+names [#]_.
 
 Egg structure
 ~~~~~~~~~~~~~
-Script library is distributed as an python egg. Making it easy to distribute
-it and install either to system or user directory.
+Script library is distributed as an python egg, making it easy to distribute
+and install either to system or user directory.
 
 Following tree shows directory structure of *service* egg residing in
 `upstream git`_: ::
@@ -357,9 +359,9 @@ This library then can be imported with: ::
     from lmi.scripts import service
 
 ``commands/service/scripts/service`` must be a package (directory with
-``__init__.py``) because ``lmi.scripts`` is a namespace package. It can have
-arbitrary number of modules and subpackages. The care should be taken to make
-the API easy to use and learn though.
+``__init__.py``) because ``lmi.scripts`` is a namespace package. It
+can have arbitrary number of modules and subpackages. The care should be taken
+to make the API easy to use and learn though.
 
 Writing ``setup.py``
 --------------------
@@ -387,12 +389,13 @@ Follows a minimal example of ``setup.py`` script for service library. ::
 .. _entry_points:
 
 The most notable argument here is ``entry_points`` which is a dictionary
-containing python namespaces, where plugins are registered. In this case, we
+containing python namespaces where plugins are registered. In this case, we
 register single top-level command (see `Top-level commands`_) called
-``service`` in ``lmi.scripts.cmd`` namespace. This particular namespace is
-used by ``lmi`` meta-command when searching of registered user commands.
-``Service`` is a command multiplexer, created with a call to
-``register_subcommands()`` grouping end-point commands together.
+``service`` in ``lmi.scripts.cmd`` namespace. This particular namespace is used
+by ``lmi`` meta-command when searching of registered user commands. ``Service``
+is a command multiplexer, created with a call to
+:py:func:`lmi.scripts.common.command.helper.register_subcommands` grouping
+end-point commands together.
 
 Next example shows setup with more top-level commands
 (of storage scripts library): ::
@@ -433,8 +436,9 @@ These pages provide more details of some aspects:
 
 .. [#] Described by a POSIX.
 .. [#] Default namespace is ``"root/cimv2"``.
-.. [#] ssh://git.fedorahosted.org/git/openlmi-providers.git/
-.. [#] Simplified here means, that there are no documentation strings
+.. [#] view: https://fedorahosted.org/openlmi/browser/openlmi-providers
+       git: ``ssh://git.fedorahosted.org/git/openlmi-providers.git/``
+.. [#] Simplified here means that there are no documentation strings
        and no type checking.
 .. [#] If logging to a file is enabled in configuration.
 .. [#] Precisely in an ``__init__.py`` module of this package.