From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Wed, 24 Jul 2013 11:10:15 +0000 (+0200)
Subject: Updated and corrected date docs
X-Git-Tag: 1.0~52
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bc30eb47a605e60549043bab3ca4a90b952fd20d;p=thirdparty%2Fbabel.git

Updated and corrected date docs
---

diff --git a/docs/conf.py b/docs/conf.py
index 9e3d3065..65216c30 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -26,7 +26,8 @@ sys.path.append(os.path.abspath('_themes'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode',
+              'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -249,3 +250,7 @@ texinfo_documents = [
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+intersphinx_mapping = {
+    'http://docs.python.org/dev': None,
+}
diff --git a/docs/dates.rst b/docs/dates.rst
index 12d15ee3..5d43be50 100644
--- a/docs/dates.rst
+++ b/docs/dates.rst
@@ -1,17 +1,15 @@
 .. -*- mode: rst; encoding: utf-8 -*-
 
-===============
-Date Formatting
-===============
+=============
+Date and Time
+=============
 
 
 When working with date and time information in Python, you commonly use the
-classes ``date``, ``datetime`` and/or ``time`` from the `datetime`_ package.
+classes ``date``, ``datetime`` and/or ``time`` from the `datetime` package.
 Babel provides functions for locale-specific formatting of those objects in its
 ``dates`` module:
 
-.. _`datetime`: http://docs.python.org/lib/module-datetime.html
-
 .. code-block:: pycon
 
     >>> from datetime import date, datetime, time
@@ -45,6 +43,32 @@ For example:
     >>> format_date(d, format='full', locale='en')
     u'Sunday, April 1, 2007'
 
+Core Time Concepts
+==================
+
+Working with dates and time can be a complicated thing.  Babel attempts to
+simplify working with them by making some decisions for you.  Python's
+datetime module knows to different ways to deal with times and dates:
+naive and timezone aware datetime objects.
+
+Babel generally recommends you to store all your time in naive datetime
+objects and treat them as UTC at all times.  This simplifies dealing with
+time a lot because otherwise you can get into the hairy situation where
+you are dealing with datetime objects of different timezones.  That is
+tricky because there are situations where time can be ambiguous.  This is
+usually the case when dealing with dates around timezone transitions.  The
+most common case of timezone transition is changes between daylight saving
+time and standard time.
+
+As such we recommend to always use UTC internally and only reformat to
+local time when returning dates to users.  At that point the timezone the
+user has selected can usually be established and Babel can automatically
+rebase the time for you.
+
+To get the current time use the `datetime.datetime.utcnow` method.  It
+will return a naive ``datetime`` object in UTC.
+
+For more information about timezones see :ref:`timezone-support`.
 
 Pattern Syntax
 ==============
@@ -231,6 +255,7 @@ can limit the smallest unit to display:
     >>> format_timedelta(delta, granularity='month', locale='en_US')
     u'1 month'
 
+.. _timezone-support:
 
 Time-zone Support
 =================
@@ -332,15 +357,3 @@ display a list of time-zones to the user.
     u'Mitteleurop\xe4ische Sommerzeit'
     >>> get_timezone_name(tz, locale=Locale.parse('de_DE'))
     u'Deutschland'
-
-
-Parsing Dates
-=============
-
-Babel can also parse date and time information in a locale-sensitive manner:
-
-.. code-block:: pycon
-
-    >>> from babel.dates import parse_date, parse_datetime, parse_time
-
-.. note:: Date/time parsing is not properly implemented yet
diff --git a/docs/index.rst b/docs/index.rst
index 220607c7..96986fba 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -4,13 +4,16 @@
 Babel
 =====
 
+Babel is an integrated collection of utilities that assist in
+internationalizing and localizing Python applications, with an emphasis on
+web-based applications.
+
 ------------------
 User Documentation
 ------------------
 
-Babel is an integrated collection of utilities that assist in
-internationalizing and localizing Python applications, with an emphasis on
-web-based applications.
+The user documentation explains some core concept of the library and gives
+some information about how it can be used.
 
 .. toctree::
    :maxdepth: 1
@@ -28,6 +31,8 @@ web-based applications.
 API Reference
 -------------
 
+The API reference lists the full public API that Babel provides.
+
 .. toctree::
    :maxdepth: 1