Merge "Improve initial documentation"

12 files changed, 304 insertions, 41 deletions

diff --git a/README.rst b/README.rst
index aef7e98..d83e57f 100644
--- a/README.rst
+++ b/README.rst
@@ -1,8 +1,10 @@
-===========
- oslo.i18n
-===========
+==================================================
+ oslo.i18n -- Oslo Internationalization Utilities
+==================================================
 
-oslo.i18n library
+The oslo.i18n library contain utilities for working with
+internationalization (i18n) features, especially translation for text
+strings in an application or library.
 
 * Free software: Apache license
 * Documentation: http://docs.openstack.org/developer/oslo.i18n
diff --git a/doc/source/api.rst b/doc/source/api.rst
new file mode 100644
index 0000000..480a772
--- /dev/null
+++ b/doc/source/api.rst
@@ -0,0 +1,33 @@
+=====
+ API
+=====
+
+oslo.i18n.gettextutils
+======================
+
+.. automodule:: oslo.i18n.gettextutils
+
+.. autoclass:: oslo.i18n.gettextutils.TranslatorFactory
+   :members:
+
+.. seealso::
+
+   An example of using a :class:`TranslatorFactory` is provided in
+   :ref:`integration-module`.
+
+.. autofunction:: oslo.i18n.gettextutils.enable_lazy
+
+.. seealso::
+
+   :ref:`lazy-translation`
+
+.. autofunction:: oslo.i18n.gettextutils.translate
+
+.. autofunction:: oslo.i18n.gettextutils.get_available_languages
+
+oslo.i18n.log
+=============
+
+.. automodule:: oslo.i18n.log
+   :members:
+
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 7e0ed38..ef1b1b3 100755
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -58,6 +58,8 @@ pygments_style = 'sphinx'
 # html_theme = '_theme'
 # html_static_path = ['static']
 
+html_use_modindex = True
+
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
 
@@ -72,4 +74,4 @@ latex_documents = [
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.
-#intersphinx_mapping = {'http://docs.python.org/': None}
\ No newline at end of file
+#intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst
index 8cb3146..2ca75d1 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributing.rst
@@ -1 +1,5 @@
-.. include:: ../../CONTRIBUTING.rst
\ No newline at end of file
+==============
+ Contributing
+==============
+
+.. include:: ../../CONTRIBUTING.rst
diff --git a/doc/source/guidelines.rst b/doc/source/guidelines.rst
new file mode 100644
index 0000000..18dbe3c
--- /dev/null
+++ b/doc/source/guidelines.rst
@@ -0,0 +1,168 @@
+=================================
+ Guidelines for Use In OpenStack
+=================================
+
+Text messages the user sees via exceptions or API calls should be
+translated using
+:py:attr:`TranslatorFactory.primary <oslo.i18n.gettextutils.TranslatorFactory.primary>`, which should
+be installed as ``_()`` in the integration module.
+
+.. seealso::
+
+   * :doc:`usage`
+   * :doc:`api`
+
+Log Translation
+===============
+
+OpenStack supports translating some log levels using separate message
+catalogs, and so has separate marker functions. These well-known names
+are used by the build system jobs that extract the messages from the
+source code and pass it to the translation tool.
+
+========== ==========
+ Level      Function
+========== ==========
+ INFO       ``_LI()``
+ WARNING    ``_LW()``
+ ERROR      ``_LE()``
+ CRITICAL   ``_LC()``
+========== ==========
+
+.. note:: Debug level log messages are not translated.
+
+Choosing a Marker Function
+==========================
+
+The purpose of the different marker functions is to separate the
+translatable messages into different catalogs, which the translation
+teams can prioritize translating. It is important to choose the right
+marker function, to ensure that strings the user sees will be
+translated and to help the translation team manage their work load.
+
+Everything marked with ``_()`` will be translated. Prioritizing the
+catalogs created from strings marked with the log marker functions is
+up to the individual translation teams and their users, but it is
+expected that they will work on critical and error messages before
+warning or info.
+
+Examples
+--------
+
+``_()`` is preferred for any user facing message, even if it is also
+going to a log file.
+
+A common pattern is to define a single message object and use it more
+than once, for the log call and the exception. In that case, use
+``_()`` because the message is going to appear in an exception that
+may be presented to the user.
+
+**Do not do this**::
+
+  # WRONG
+  msg = _LE('There was an error.')
+  LOG.exception(msg)
+  raise LocalExceptionClass(msg)
+
+Instead, use this style::
+
+  # RIGHT
+  msg = _('There was an error.')
+  LOG.exception(msg)
+  raise LocalExceptionClass(msg)
+
+Except in the case above, ``_()`` should not be used for translating
+log messages. This avoids having the same string in two message
+catalogs, possibly translated differently by two different
+translators.
+
+For example, **do not do this**::
+
+  # WRONG
+  LOG.exception(_('There was an error.'))
+  raise LocalExceptionClass(_('An error occured.'))
+
+Instead, use this style::
+
+  # RIGHT
+  LOG.exception(_LE('There was an error.'))
+  raise LocalExceptionClass(_('An error occured.'))
+
+
+Adding Variables to Translated Messages
+=======================================
+
+Translated messages should not be combined with other literal strings
+to create partially translated messages.  For example, **do not do
+this**::
+
+  # WRONG
+  raise ValueError(_('some message') + ': variable=%s') % variable)
+
+Instead, use this style::
+
+  # RIGHT
+  raise ValueError(_('some message: variable=%s') % variable)
+
+Including the variable reference inside the translated message allows
+the translator to take into account grammar rules, differences in
+left-right vs. right-left rendering, and other factors to make the
+translated message more useful to the end user.
+
+Any message with more than one variable should use named interpolation
+instead of positional, to allow translators to move the variables
+around in the string to account for differences in grammar and writing
+direction.
+
+For example, **do not do this**::
+
+  # WRONG
+  raise ValueError(_('some message: v1=%s v2=%s') % (v1, v2))
+
+Instead, use this style::
+
+  # RIGHT
+  raise ValueError(_('some message: v1=%(v1)s v2=%(v2)s') % {'v1': v1, 'v2': v2})
+
+
+Adding Variables to Log Messages
+================================
+
+String interpolation should be delayed to be handled by the logging
+code, rather than being done at the point of the logging call.  For
+example, **do not do this**::
+
+  # WRONG
+  LOG.info(_LI('some message: variable=%s') % variable)
+
+Instead, use this style::
+
+  # RIGHT
+  LOG.info(_LI('some message: variable=%s'), variable)
+
+This allows the logging package to skip creating the formatted log
+message if the message is not going to be emitted because of the
+current log level.
+
+Avoid Forcing the  Translation of Translatable Variables
+========================================================
+
+Translation can also be delayed for variables that potentially contain
+translatable objects such as exceptions.
+
+Whenever possible translation should not be forced by use of :func:`str`,
+:func:`unicode`, or :func:`six.text_type` on a message being used with
+a format string.
+
+For example, **do not do this**::
+
+  # WRONG
+  LOG.info(_LI('some message: exception=%s', six.text_type(exc)))
+
+Instead, use this style::
+
+  # RIGHT
+  LOG.info(_LI('some message: exception=%s', exc))
+
+This allows the translation of the translatable replacement text to be
+delayed until the message is translated.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 6394002..1ed4fed 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,24 +1,24 @@
-..  documentation master file, created by
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+==================================================
+ oslo.i18n -- Oslo Internationalization Utilities
+==================================================
 
-Welcome to 's documentation!
-========================================================
+The oslo.i18n library contain utilities for working with
+internationalization (i18n) features, especially translation for text
+strings in an application or library.
 
-Contents:
+Contents
+========
 
 .. toctree::
    :maxdepth: 2
 
-   readme
-   installation
    usage
+   guidelines
+   api
    contributing
 
 Indices and tables
 ==================
 
-* :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
deleted file mode 100644
index 5c01c7a..0000000
--- a/doc/source/installation.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-============
-Installation
-============
-
-At the command line::
-
-    $ pip install 
-
-Or, if you have virtualenvwrapper installed::
-
-    $ mkvirtualenv 
-    $ pip install 
\ No newline at end of file
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index a6210d3..0000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../README.rst
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index 55ebe00..89f054f 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -1,11 +1,23 @@
-=======
- Usage
-=======
+=====================================================
+ How to Use oslo.i18n in Your Application or Library
+=====================================================
 
-Integration Module
-==================
+Installing
+==========
 
-To use in a project, create a small integration module containing:
+At the command line::
+
+    $ pip install oslo.i18n
+
+.. _integration-module:
+
+Creating an Integration Module
+==============================
+
+To use oslo.i18n in a project, you will need to create a small
+integration module to hold an instance of
+:class:`~oslo.i18n.gettextutils.TranslatorFactory` and references to
+the marker functions the factory creates.
 
 ::
 
@@ -26,8 +38,8 @@ To use in a project, create a small integration module containing:
     _LE = _translators.log_error
     _LC = _translators.log_critical
 
-Then, in your application code, use the appropriate marker function
-for your case:
+Then, in the rest of your code, use the appropriate marker function
+for each message:
 
 ::
 
@@ -41,6 +53,17 @@ for your case:
 
     raise RuntimeError(_('exception message'))
 
+.. warning::
+
+   The old method of installing a version of ``_()`` in the builtins
+   namespace is deprecated. Modifying the global namespace affects
+   libraries as well as the application, so it may interfere with
+   proper message catalog lookups. Calls to
+   :func:`gettextutils.install` should be replaced with the
+   application or library integration module described here.
+
+.. _lazy-translation:
+
 Lazy Translation
 ================
 
@@ -65,3 +88,39 @@ To enable lazy translation, call :func:`enable_lazy`.
     from oslo.i18n import gettextutils
 
     gettextutils.enable_lazy()
+
+Translating Messages
+====================
+
+Use :func:`~oslo.i18n.gettextutils.translate` to translate strings to
+a specific locale. :func:`translate` handles delayed translation and
+strings that have already been translated immediately. It should be
+used at the point where the locale to be used is known, which is often
+just prior to the message being returned or a log message being
+emitted.
+
+::
+
+    from oslo.i18n import gettextutils
+
+    trans_msg = gettextutils.translate(msg, desired_locale=my_locale)
+
+if desired_locale is not specified then the default locale is used.
+
+Available Languages
+===================
+
+Only the languages that have translations provided are available for
+translation. To determine which languages are available the
+:func:`~oslo.i18n.gettextutils.get_available_languages` is provided. Since different languages
+can be installed for each domain, the domain must be specified.
+
+::
+
+      from oslo.i18n import gettextutils
+
+      avail_lang = gettextutils.get_available_languages('myapp')
+
+.. seealso::
+
+   * :doc:`guidelines`
diff --git a/oslo/i18n/log.py b/oslo/i18n/log.py
index 46d6c1e..a2bd4c8 100644
--- a/oslo/i18n/log.py
+++ b/oslo/i18n/log.py
@@ -29,7 +29,8 @@ class TranslationHandler(handlers.MemoryHandler):
     to forward LogRecord objects to after translating them. This handler
     depends on Message objects being logged, instead of regular strings.
 
-    The handler can be configured declaratively in the logging.conf as follows:
+    The handler can be configured declaratively in the
+    ``logging.conf`` as follows::
 
         [handlers]
         keys = translatedlog, translator
@@ -40,12 +41,13 @@ class TranslationHandler(handlers.MemoryHandler):
         formatter = context
 
         [handler_translator]
-        class = openstack.common.log.TranslationHandler
+        class = oslo.i18n.log.TranslationHandler
         target = translatedlog
         args = ('zh_CN',)
 
     If the specified locale is not available in the system, the handler will
     log in the default locale.
+
     """
 
     def __init__(self, locale=None, target=None):
diff --git a/setup.cfg b/setup.cfg
index 763fa8f..9c31110 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -46,4 +46,7 @@ input_file = oslo.i18n/locale/oslo.i18n.pot
 [extract_messages]
 keywords = _ gettext ngettext l_ lazy_gettext
 mapping_file = babel.cfg
-output_file = oslo.i18n/locale/oslo.i18n.pot
\ No newline at end of file
+output_file = oslo.i18n/locale/oslo.i18n.pot
+
+[pbr]
+warnerrors = True
diff --git a/tox.ini b/tox.ini
index 5d9ffa4..c969b2c 100644
--- a/tox.ini
+++ b/tox.ini
@@ -22,6 +22,9 @@ commands = flake8
 [testenv:venv]
 commands = {posargs}
 
+[testenv:docs]
+commands = python setup.py build_sphinx
+
 [testenv:cover]
 commands = python setup.py testr --coverage --testr-args='{posargs}'
 
@@ -36,4 +39,4 @@ exclude=.venv,.git,.tox,dist,doc,*openstack/common*,*lib/python*,*egg,build,
 
 [hacking]
 import_exceptions =
-    oslo.i18n._i18n._
\ No newline at end of file
+    oslo.i18n._i18n._