Fix up usage instructions

Clean up the documentation a little bit and write slightly
more verbose (and correct) instructions for using the library.

bp graduate-oslo-i18n

Change-Id: Ice626b6eae3c02be84cf79a1ad57817ec8736d8a

README.rst

@@ -1,10 +1,10 @@
-===================================
-oslo.i18n
-===================================
+===========
+ oslo.i18n
+===========
 
 oslo.i18n library
 
 * Free software: Apache license
 * Documentation: http://docs.openstack.org/developer/oslo.i18n
 * Source: http://git.openstack.org/cgit/openstack/oslo.i18n
-* Bugs: http://bugs.launchpad.net/oslo
+* Bugs: http://bugs.launchpad.net/oslo

doc/source/readme.rst

@@ -1 +1 @@
-.. include:: ../README.rst
+.. include:: ../../README.rst

doc/source/usage.rst

@@ -1,7 +1,39 @@
-========
-Usage
-========
+=======
+ Usage
+=======
 
-To use  in a project::
+To use in a project, create a small integration module containing:
 
-	import i18n
+::
+
+	from oslo.i18n import gettextutils
+
+    _translators = gettextutils.TranslatorFactory(domain='myapp')
+
+    # The primary translation function using the well-known name "_"
+    _ = _translators.primary
+
+    # Translators for log levels.
+    #
+    # The abbreviated names are meant to reflect the usual use of a short
+    # name like '_'. The "L" is for "log" and the other letter comes from
+    # the level.
+    _LI = _translators.log_info
+    _LW = _translators.log_warning
+    _LE = _translators.log_error
+    _LC = _translators.log_critical
+
+Then, in your application code, use the appropriate marker function
+for your case:
+
+::
+
+    from myapp.i18n import _, _LW
+
+    # ...
+
+    LOG.warn(_LW('warning message: %s'), var)
+
+    # ...
+
+    raise RuntimeError(_('exception message'))

oslo/i18n/gettextutils.py

@@ -14,12 +14,7 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-"""
-gettext for openstack-common modules.
-
-Usual usage in an openstack.common module:
-
-    from openstack.common.gettextutils import _
+"""gettextutils provides a wrapper around gettext for OpenStack projects
 """
 
 import copy