Updated and corrected date docs

diff --git a/docs/conf.py b/docs/conf.py
index 9e3d30653e0c05ca07626bb5d22d76016be2d6ff..65216c30502dcbedd9603630d670d864f5656c07 100644 (file)
--- 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 12d15ee3b85278c246fc5135d26d32675ce9ad4d..5d43be507f7e9a85a361dc21a7e17d86145efee8 100644 (file)
--- 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 220607c74b0a30166babd8f988236af7fa79e06a..96986fba60ccbe8b7ded2d837f6a11554ae21ce4 100644 (file)
--- 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