New API docs

diff --git a/babel/core.py b/babel/core.py
index 1c7e335d7755cc1f472b00ee6cc5061ad31a7180..6b9cd41ed33589aeaf234947bd507fa3125b39d8 100644 (file)
--- a/babel/core.py
+++ b/babel/core.py
@@ -169,6 +169,8 @@ class Locale(object):
         :param category: one of the ``LC_XXX`` environment variable names
         :param aliases: a dictionary of aliases for locale identifiers
         """
+        # XXX: use likely subtag expansion here instead of the
+        # aliases dictionary.
         locale_string = default_locale(category, aliases=aliases)
         return cls.parse(locale_string)
 
@@ -916,6 +918,9 @@ def get_locale_identifier(tup, sep='_'):
     of a ``(language, territory, script, variant)`` tuple.  Items can be set to
     ``None`` and trailing ``None``\s can also be left out of the tuple.
 
+    >>> get_locale_identifier(('de', 'DE', None, '1999'))
+    'de_DE_1999'
+
     .. versionadded:: 1.0
 
     :param tup: the tuple as returned by :func:`parse_locale`.

diff --git a/docs/_themes/babel/static/babel.css_t b/docs/_themes/babel/static/babel.css_t
index e7d2116b581d42cb4a60a46796c2dacc7ac589ea..3f36d20b945b44d318c71b0decca83bc3348bda5 100644 (file)
--- a/docs/_themes/babel/static/babel.css_t
+++ b/docs/_themes/babel/static/babel.css_t
@@ -377,7 +377,6 @@ dl dl pre {
 tt {
     background-color: #ecf0f3;
     color: #222;
-    padding: 3px 6px;
     -webkit-border-radius: 3px;
     -moz-border-radius: 3px;
     border-radius: 3px;

diff --git a/docs/api/babel.core.rst b/docs/api/babel.core.rst
deleted file mode 100644 (file)
index acc63af..0000000
--- a/docs/api/babel.core.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-==========
-babel.core
-==========
-
-.. automodule:: babel.core
-    :members:

diff --git a/docs/api/babel.dates.rst b/docs/api/babel.dates.rst
deleted file mode 100644 (file)
index 639b279..0000000
--- a/docs/api/babel.dates.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-===========
-babel.dates
-===========
-
-.. automodule:: babel.dates
-    :members:

diff --git a/docs/api/babel.localedata.rst b/docs/api/babel.localedata.rst
deleted file mode 100644 (file)
index bdca426..0000000
--- a/docs/api/babel.localedata.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-================
-babel.localedata
-================
-
-.. automodule:: babel.localedata
-    :members:

diff --git a/docs/api/babel.messages.catalog.rst b/docs/api/babel.messages.catalog.rst
deleted file mode 100644 (file)
index b6edb49..0000000
--- a/docs/api/babel.messages.catalog.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-======================
-babel.messages.catalog
-======================
-
-.. automodule:: babel.messages.catalog
-    :members:

diff --git a/docs/api/babel.messages.checkers.rst b/docs/api/babel.messages.checkers.rst
deleted file mode 100644 (file)
index 2d58631..0000000
--- a/docs/api/babel.messages.checkers.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-=======================
-babel.messages.checkers
-=======================
-
-.. automodule:: babel.messages.checkers
-    :members:

diff --git a/docs/api/babel.messages.extract.rst b/docs/api/babel.messages.extract.rst
deleted file mode 100644 (file)
index e846f38..0000000
--- a/docs/api/babel.messages.extract.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-======================
-babel.messages.extract
-======================
-
-.. automodule:: babel.messages.extract
-    :members:

diff --git a/docs/api/babel.messages.frontend.rst b/docs/api/babel.messages.frontend.rst
deleted file mode 100644 (file)
index 0ca45ca..0000000
--- a/docs/api/babel.messages.frontend.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-=======================
-babel.messages.frontend
-=======================
-
-.. automodule:: babel.messages.frontend
-    :members:

diff --git a/docs/api/babel.messages.mofile.rst b/docs/api/babel.messages.mofile.rst
deleted file mode 100644 (file)
index 57919e7..0000000
--- a/docs/api/babel.messages.mofile.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-=====================
-babel.messages.mofile
-=====================
-
-.. automodule:: babel.messages.mofile
-    :members:

diff --git a/docs/api/babel.messages.plurals.rst b/docs/api/babel.messages.plurals.rst
deleted file mode 100644 (file)
index 38ee7c6..0000000
--- a/docs/api/babel.messages.plurals.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-======================
-babel.messages.plurals
-======================
-
-.. automodule:: babel.messages.plurals
-    :members:

diff --git a/docs/api/babel.messages.pofile.rst b/docs/api/babel.messages.pofile.rst
deleted file mode 100644 (file)
index 8d3cc3f..0000000
--- a/docs/api/babel.messages.pofile.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-=====================
-babel.messages.pofile
-=====================
-
-.. automodule:: babel.messages.pofile
-    :members:

diff --git a/docs/api/babel.messages.rst b/docs/api/babel.messages.rst
deleted file mode 100644 (file)
index 4bc9ef1..0000000
--- a/docs/api/babel.messages.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-==============
-babel.messages
-==============
-
-.. automodule:: babel.messages
-    :members:

diff --git a/docs/api/babel.numbers.rst b/docs/api/babel.numbers.rst
deleted file mode 100644 (file)
index 8ac643d..0000000
--- a/docs/api/babel.numbers.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-=============
-babel.numbers
-=============
-
-.. automodule:: babel.numbers
-    :members:

diff --git a/docs/api/babel.support.rst b/docs/api/babel.support.rst
deleted file mode 100644 (file)
index 58d0b98..0000000
--- a/docs/api/babel.support.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-=============
-babel.support
-=============
-
-.. automodule:: babel.support
-    :members:

diff --git a/docs/api/babel.util.rst b/docs/api/babel.util.rst
deleted file mode 100644 (file)
index fa59470..0000000
--- a/docs/api/babel.util.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-==========
-babel.util
-==========
-
-.. automodule:: babel.util
-    :members:

diff --git a/docs/api/core.rst b/docs/api/core.rst
new file mode 100644 (file)
index 0000000..e554938
--- /dev/null
+++ b/docs/api/core.rst
@@ -0,0 +1,35 @@
+Core Functionality
+==================
+
+.. module:: babel.core
+
+The core API provides the basic core functionality.  Primarily it provides
+the :class:`Locale` object and ways to create it.  This object
+encapsulates a locale and exposes all the data it contains.
+
+Basic Interface
+---------------
+
+.. autoclass:: Locale
+   :members:
+
+.. autofunction:: default_locale
+
+.. autofunction:: negotiate_locale
+
+
+Exceptions
+----------
+
+.. autoexception:: UnknownLocaleError
+   :members:
+
+
+Utility Functions
+-----------------
+
+.. autofunction:: get_global
+
+.. autofunction:: parse_locale
+
+.. autofunction:: get_locale_identifier

diff --git a/docs/api/dates.rst b/docs/api/dates.rst
new file mode 100644 (file)
index 0000000..7186350
--- /dev/null
+++ b/docs/api/dates.rst
@@ -0,0 +1,67 @@
+Date and Time
+=============
+
+.. module:: babel.dates
+
+The date and time functionality provided by Babel lets you format standard
+Python `datetime`, `date` and `time` objects and and work with timezones.
+
+Date and Time Formatting
+------------------------
+
+.. autofunction:: format_datetime
+
+.. autofunction:: format_date
+
+.. autofunction:: format_time
+
+.. autofunction:: format_timedelta
+
+Timezone Functionality
+----------------------
+
+.. autofunction:: get_timezone
+
+.. autofunction:: get_timezone_gmt
+
+.. autofunction:: get_timezone_location
+
+.. autofunction:: get_timezone_name
+
+.. autofunction:: get_next_timezone_transition
+
+.. data:: UTC
+
+    A timezone object for UTC.
+
+.. data:: LOCALTZ
+
+    A timezone object for the computer's local timezone.
+
+Data Access
+-----------
+
+.. autofunction:: get_period_names
+
+.. autofunction:: get_day_names
+
+.. autofunction:: get_month_names
+
+.. autofunction:: get_quarter_names
+
+.. autofunction:: get_era_names
+
+.. autofunction:: get_date_format
+
+.. autofunction:: get_datetime_format
+
+.. autofunction:: get_time_format
+
+Basic Parsing
+-------------
+
+.. autofunction:: parse_date
+
+.. autofunction:: parse_time
+
+.. autofunction:: parse_pattern

diff --git a/docs/api/index.rst b/docs/api/index.rst
new file mode 100644 (file)
index 0000000..9222cf1
--- /dev/null
+++ b/docs/api/index.rst
@@ -0,0 +1,14 @@
+API Reference
+=============
+
+This part of the documentation contains the full API reference of the
+public API of Babel.
+
+.. toctree::
+   :maxdepth: 2
+
+   core
+   dates
+   numbers
+   plural
+   support

diff --git a/docs/api/numbers.rst b/docs/api/numbers.rst
new file mode 100644 (file)
index 0000000..de3573e
--- /dev/null
+++ b/docs/api/numbers.rst
@@ -0,0 +1,45 @@
+Numbers
+=======
+
+.. module:: babel.numbers
+
+The number module provides functionality to format numbers for different
+locales.  This includes arbitrary numbers as well as currency.
+
+Number Formatting
+-----------------
+
+.. autofunction:: format_number
+
+.. autofunction:: format_decimal
+
+.. autofunction:: format_currency
+
+.. autofunction:: format_percent
+
+.. autofunction:: format_scientific
+
+Number Parsing
+--------------
+
+.. autofunction:: parse_number
+
+.. autofunction:: parse_decimal
+
+Exceptions
+----------
+
+.. autoexception:: NumberFormatError
+
+Data Access
+-----------
+
+.. autofunction:: get_currency_name
+
+.. autofunction:: get_currency_symbol
+
+.. autofunction:: get_decimal_symbol
+
+.. autofunction:: get_plus_sign_symbol
+
+.. autofunction:: get_minus_sign_symbol

diff --git a/docs/api/plural.rst b/docs/api/plural.rst
new file mode 100644 (file)
index 0000000..d6934b5
--- /dev/null
+++ b/docs/api/plural.rst
@@ -0,0 +1,23 @@
+Pluralization Support
+=====================
+
+.. module:: babel.plural
+
+The pluralization support provides functionality around the CLDR
+pluralization rules.  It can parse and evaluate pluralization rules, as
+well as convert them to other formats such as gettext.
+
+Basic Interface
+---------------
+
+.. autoclass:: PluralRule
+   :members:
+
+Conversion Functionality
+------------------------
+
+.. autofunction:: to_javascript
+
+.. autofunction:: to_python
+
+.. autofunction:: to_gettext

diff --git a/docs/api/support.rst b/docs/api/support.rst
new file mode 100644 (file)
index 0000000..fa638ba
--- /dev/null
+++ b/docs/api/support.rst
@@ -0,0 +1,22 @@
+General Support Functionality
+=============================
+
+.. module:: babel.support
+
+Babel ships a few general helpers that are not being used by Babel itself
+but are useful in combination with functionality provided by it.
+
+Convenience Helpers
+-------------------
+
+.. autoclass:: Format
+   :members:
+
+.. autoclass:: LazyProxy
+   :members:
+
+Gettext Support
+---------------
+
+.. autoclass:: Translations
+   :members:

diff --git a/docs/index.rst b/docs/index.rst
index 96986fba60ccbe8b7ded2d837f6a11554ae21ce4..474a10c91392e7dd12da3d0e9ee5f3aa7815c513 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,6 +1,5 @@
 .. -*- mode: rst; encoding: utf-8 -*-
 
-=====
 Babel
 =====
 
@@ -8,7 +7,6 @@ Babel is an integrated collection of utilities that assist in
 internationalizing and localizing Python applications, with an emphasis on
 web-based applications.
 
-------------------
 User Documentation
 ------------------
 
@@ -27,26 +25,12 @@ some information about how it can be used.
    setup
    support
 
--------------
 API Reference
 -------------
 
 The API reference lists the full public API that Babel provides.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   api/babel.core
-   api/babel.dates
-   api/babel.localedata
-   api/babel.messages
-   api/babel.messages.catalog
-   api/babel.messages.checkers
-   api/babel.messages.extract
-   api/babel.messages.frontend
-   api/babel.messages.mofile
-   api/babel.messages.plurals
-   api/babel.messages.pofile
-   api/babel.numbers
-   api/babel.support
-   api/babel.util
+   api/index