Fix guidelines w.r.t. translation of log messages

Translation of log messages was ceased starting with Pike, but only
the oslo.i18n documentation was only partially updated (by
Ia34ad79ca9), and not this repository.

So remove misleading examples of log translation from this
documentation.

Change-Id: Ib86013ff5e7bd07ddc696da2e4c56ce9d07f0cb6

doc/source/user/examples.rst

@@ -43,14 +43,6 @@ usage_helper.py
 .. literalinclude:: examples/usage_helper.py
    :linenos:
 
-usage_i18n.py
--------------
-
-.. _example_usage_i18n.py:
-
-.. literalinclude:: examples/usage_i18n.py
-   :linenos:
-
 usage_context.py
 ----------------
 

doc/source/user/examples/usage_i18n.py

@@ -1,87 +0,0 @@
-# Copyright (c) 2016 OpenStack Foundation
-#
-# Licensed under the Apache License, Version 2.0 (the "License"); you may
-# not use this file except in compliance with the License. You may obtain
-# a copy of the License at
-#
-#   http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-# License for the specific language governing permissions and limitations
-# under the License.
-
-"""A usage example of Oslo Logging with Oslo i18n
-
-This example requires the following package to be installed.
-$ pip install oslo.log
-
-Additional Oslo packages installed include oslo.config, oslo.context,
-oslo.i18n, oslo.serialization and oslo.utils.
-
-More information about Oslo Logging can be found at:
-
-  https://docs.openstack.org/oslo.log/latest/user/index.html
-  https://docs.openstack.org/oslo.i18n/latest/user/index.html  
-"""
-
-from oslo_config import cfg
-from oslo_log import log as logging
-from _i18n import _, _LI, _LW, _LE  # noqa
-
-LOG = logging.getLogger(__name__)
-CONF = cfg.CONF
-DOMAIN = 'demo'
-
-
-def prepare():
-    """Prepare Oslo Logging (2 or 3 steps)
-
-    Use of Oslo Logging involves the following:
-
-    * logging.register_options
-    * logging.set_defaults (optional)
-    * logging.setup
-    """
-
-    # Required step to register common, logging and generic configuration
-    # variables
-    logging.register_options(CONF)
-
-    # Optional step to set new defaults if necessary for
-    # * logging_context_format_string
-    # * default_log_levels
-    #
-    # These variables default to respectively:
-    #
-    #  import oslo_log
-    #  oslo_log._options.DEFAULT_LOG_LEVELS
-    #  oslo_log._options.log_opts[0].default
-    #
-
-    extra_log_level_defaults = [
-        'dogpile=INFO',
-        'routes=INFO'
-        ]
-
-    logging.set_defaults(
-        default_log_levels=logging.get_default_log_levels() +
-        extra_log_level_defaults)
-
-    # Required setup based on configuration and domain
-    logging.setup(CONF, DOMAIN)
-
-
-if __name__ == '__main__':
-    prepare()
-    # NOTE: These examples use Oslo i18n marker functions
-
-    LOG.info(_LI("Welcome to Oslo Logging"))
-    LOG.debug("A debugging message")  # Debug messages are not translated
-    LOG.warning(_LW("A warning occurred"))
-    LOG.error(_LE("An error occurred"))
-    try:
-        raise Exception(_("This is exceptional"))
-    except Exception:
-        LOG.exception(_LE("An Exception occurred"))

doc/source/user/usage.rst

@@ -85,17 +85,16 @@ log levels.
     2016-01-14 21:07:51.396 12945 ERROR __main__ None
     2016-01-14 21:07:51.396 12945 ERROR __main__
 
-Logging within an application should use `Oslo International Utilities (i18n)`_ marker
+Oslo Log Translation
-functions to provide language translation capabilities.
+--------------------
 
-.. _Oslo International Utilities (i18n): https://docs.openstack.org/oslo.i18n/latest
+As of the Pike release, `logging within an application should no
+longer use Oslo International Utilities (i18n) marker functions
+<https://docs.openstack.org/oslo.i18n/latest/user/guidelines.html#log-translation>`_
+to provide language translation capabilities.
 
-.. literalinclude:: examples/usage_i18n.py
+Adding Context to Logging
-   :linenos:
+-------------------------
-   :lines: 31-32,76,79-85
-   :emphasize-lines: 1
-
-Source: :ref:`examples/usage_i18n.py <example_usage_i18n.py>`
 
 With the use of `Oslo Context`_, log records can also contain
 additional contextual information applicable for your application.
@@ -126,8 +125,6 @@ specified in :oslo.config:option:`logging_context_format_string`. An
 application can extend this object to provide additional attributes that can
 be specified in log records.
 
-
-
 Examples
 --------
 
@@ -138,9 +135,6 @@ example of Oslo Logging setup.
 example showing debugging logging at each step details the configuration
 and logging at each step of Oslo Logging setup.
 
-:ref:`examples/usage_i18n.py <example_usage_i18n.py>` provides a
-documented example of Oslo Logging with Oslo i18n supported messages.
-
 :ref:`examples/usage_context.py <example_usage_context.py>` provides
 a documented example of Oslo Logging with Oslo Context.