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

4 files changed, 43 insertions, 16 deletions

diff --git a/README.rst b/README.rst
index c972a9b..aef7e98 100644
--- a/README.rst
+++ b/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
\ No newline at end of file
+* Bugs: http://bugs.launchpad.net/oslo
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
index 6b2b3ec..a6210d3 100644
--- a/doc/source/readme.rst
+++ b/doc/source/readme.rst
@@ -1 +1 @@
-.. include:: ../README.rst
\ No newline at end of file
+.. include:: ../../README.rst
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 3a368fe..9ea3fa0 100644
--- a/doc/source/usage.rst
+++ b/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
\ No newline at end of file
+::
+
+	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'))
diff --git a/oslo/i18n/gettextutils.py b/oslo/i18n/gettextutils.py
index 58231e0..43f45ee 100644
--- a/oslo/i18n/gettextutils.py
+++ b/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