Added document and test case for #215

docs/settings.rst

@@ -31,7 +31,8 @@ Setting name (default value)                        what does it do?
                                                     `.html`, so you will have to setup URL rewriting on 
                                                     your web server.
 `DATE_FORMATS` (``{}``)                             If you do manage multiple languages, you can
-                                                    set the date formatting here.
+                                                    set the date formatting here. See "Date format and locales"
+                                                    section below for details.
 `DEFAULT_CATEGORY` (``'misc'``)                     The default category to fallback on.
 `DEFAULT_DATE_FORMAT` (``'%a %d %B %Y'``)           The default date format you want to use.
 `DISPLAY_PAGES_ON_MENU` (``True``)                  Display or not the pages on the menu of the
@@ -43,7 +44,7 @@ Setting name (default value)                        what does it do?
 `JINJA_EXTENSIONS` (``[]``)                         A list of any Jinja2 extensions you want to use.
 `DELETE_OUTPUT_DIRECTORY` (``False``)               Delete the output directory and just
                                                     the generated files.
-`LOCALE` (''[1]_)                                   Change the locale. A list of locales can be provided 
+`LOCALE` (''[#]_)                                   Change the locale. A list of locales can be provided 
                                                     here or a single string representing one locale.
                                                     When providing a list, all the locales will be tried 
                                                     until one works.
@@ -75,7 +76,7 @@ Setting name (default value)                        what does it do?
                                                     section below for more info.
 ================================================    =====================================================
 
-.. [1] Default is the system locale. Default is to delete the output directory.
+.. [#] Default is the system locale. Default is to delete the output directory.
 
 Article permalink structure
 ---------------------------
@@ -119,6 +120,53 @@ timezone.
 
 .. _the wikipedia page: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 
+
+Date format and locale
+----------------------
+
+If no DATE_FORMAT is set, failback to DEFAULT_DATE_FORMAT. If you need to
+maintain multiple languages with different date format, you can set this dict
+using language name( ``lang`` in your posts) as key. About available format
+codes, see `strftime document of python`_ :
+
+    DATE_FORMAT = {
+        'en': '%a, %d %b %Y',
+        'jp': '%Y-%m-%d(%a)',
+    }
+
+You can set locale to further control date format:
+
+    LOCALE = ('usa', 'jpn',  # On Windows
+        'en_US', 'ja_JP'     # On Unix/Linux
+        )
+
+Also, it is possible to set different locale settings for each language, if you
+put (locale, format) tuple in dict, and this will override the LOCALE setting
+above:
+
+    # On Unix/Linux
+    DATE_FORMAT = {
+        'en': ('en_US','%a, %d %b %Y'),
+        'jp': ('ja_JP','%Y-%m-%d(%a)'),
+    }
+
+    # On Windows
+    DATE_FORMAT = {
+        'en': ('usa','%a, %d %b %Y'),
+        'jp': ('jpn','%Y-%m-%d(%a)'),
+    }
+
+For available list of `locales on Windows` . On Unix/Linux usually you can get
+a list of available locales with command ``locale -a``, see manpage `locale(1)`
+for help.
+
+
+.. _strftime document of python: http://docs.python.org/library/datetime.html#strftime-strptime-behavior
+
+.. _locales on Windows: http://msdn.microsoft.com/en-us/library/cdax410z%28VS.71%29.aspx
+
+.. _locale(1): http://linux.die.net/man/1/locale
+
 Feed settings
 =============
 

tests/test_contents.py

@@ -65,3 +65,36 @@ class TestPage(TestCase):
         self.page_kwargs['metadata'].update({'lang': 'fr', })
         page = Page(**self.page_kwargs)
         self.assertEqual(page.save_as, "foo-bar-fr.html")
+
+    def test_datetime(self):
+        """If DATETIME is set to a tuple, it should be used to override LOCALE
+        """
+        from datetime import datetime
+        from sys import platform
+        dt = datetime(2015,9,13)
+        # make a deep copy of page_kawgs
+        page_kwargs = {key:self.page_kwargs[key] for key in self.page_kwargs}
+        for key in page_kwargs:
+            if not isinstance(page_kwargs[key], dict): break
+            page_kwargs[key] = {subkey:page_kwargs[key][subkey] for subkey in page_kwargs[key]}
+        # set its date to dt
+        page_kwargs['metadata']['date'] = dt
+        page = Page( **page_kwargs)
+
+        self.assertEqual(page.locale_date, dt.strftime(_DEFAULT_CONFIG['DEFAULT_DATE_FORMAT']))
+
+        
+        page_kwargs['settings'] = {x:_DEFAULT_CONFIG[x] for x in _DEFAULT_CONFIG}
+        # I doubt this can work on all platforms ...
+        if platform == "win32":
+            locale = 'jpn'
+        else:
+            locale = 'ja_JP'
+        page_kwargs['settings']['DATE_FORMATS'] = {'jp':(locale,'%Y-%m-%d(%a)')} 
+        page_kwargs['metadata']['lang'] = 'jp'
+        page = Page( **page_kwargs)
+        self.assertEqual(page.locale_date, u'2015-09-13(\u65e5)')
+        # above is unicode in Japanese: 2015-09-13(“ú)
+
+
+