Add documentation for `babel.languages`

Fixes #319

diff --git a/babel/languages.py b/babel/languages.py
index 28718f68d6eae5b55cbdf192ad69c17f8bff7bbe..a7708712e9f527b54008ad2c8450ea0a68d69987 100644 (file)
--- a/babel/languages.py
+++ b/babel/languages.py
@@ -12,6 +12,9 @@ def get_official_languages(territory, regional=False, de_facto=False):
 
     If the `de_facto` flag is set, then languages which are "de facto" official are also returned.
 
+    .. warning:: Note that the data is as up to date as the current version of the CLDR used
+                 by Babel.  If you need scientifically accurate information, use another source!
+
     :param territory: Territory code
     :type territory: str
     :param regional: Whether to return regionally official languages too
@@ -53,6 +56,11 @@ def get_territory_language_info(territory):
     * `official_status`: An optional string describing the officiality status of the language.
                          Known values are "official", "official_regional" and "de_facto_official".
 
+    .. warning:: Note that the data is as up to date as the current version of the CLDR used
+                 by Babel.  If you need scientifically accurate information, use another source!
+
+    .. note:: Note that the format of the dict returned may change between Babel versions.
+
     See http://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html
 
     :param territory: Territory code

diff --git a/docs/api/index.rst b/docs/api/index.rst
index b882d300b3c976ab7780af32c6ae898a7b91b04f..91f0967ca2ac09ac8f8bcf45bea4991327644aad 100644 (file)
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -10,6 +10,7 @@ public API of Babel.
    core
    dates
    lists
+   languages
    messages/index
    numbers
    plural

diff --git a/docs/api/languages.rst b/docs/api/languages.rst
new file mode 100644 (file)
index 0000000..287f1e0
--- /dev/null
+++ b/docs/api/languages.rst
@@ -0,0 +1,14 @@
+Languages
+=========
+
+.. module:: babel.languages
+
+The languages module provides functionality to access data about
+languages that is not bound to a given locale.
+
+Official Languages
+------------------
+
+.. autofunction:: get_official_languages
+
+.. autofunction:: get_territory_language_info