From: Aarni Koskela <akx@iki.fi>
Date: Fri, 8 Jan 2016 08:46:04 +0000 (+0200)
Subject: Add documentation for `babel.languages`
X-Git-Tag: 2.3.1~28^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F315%2Fhead;p=thirdparty%2Fbabel.git

Add documentation for `babel.languages`

Fixes #319
---

diff --git a/babel/languages.py b/babel/languages.py
index 28718f68..a7708712 100644
--- 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 b882d300..91f0967c 100644
--- 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
index 00000000..287f1e07
--- /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