Create global instance of command-line options

This eases testing of option values inside the code.  This instance
is implemented as the read-only copy of the obtained 'options' object,
so callers won't be able to modify its contents.

Signed-off-by: Eygene Ryabinkin <rea@codelabs.ru>

docs/doc-src/API.rst

@@ -60,3 +60,30 @@ An :class:`accounts.Account` connects two email repositories that are to be sync
    This execption inherits directly from :exc:`Exception` and is raised
    on errors during the offlineimap execution. It has an attribute
    `severity` that denotes the severity level of the error.
+
+
+:mod:`offlineimap.globals` -- module with global variables
+==========================================================
+
+.. module:: offlineimap.globals
+
+Module :mod:`offlineimap.globals` provides the read-only storage
+for the global variables.
+
+All exported module attributes can be set manually, but this practice
+is highly discouraged and shouldn't be used.
+However, attributes of all stored variables can only be read, write
+access to them is denied.
+
+Currently, we have only :attr:`options` attribute that holds
+command-line options as returned by OptionParser.
+The value of :attr:`options` must be set by :func:`set_options`
+prior to its first use.
+
+.. automodule:: offlineimap.globals
+   :members:
+
+   .. data:: options
+
+      You can access the values of stored options using the usual
+      syntax, offlineimap.globals.options.<option-name>