refactorings and started docs

docs/sphinx/Makefile

@@ -3,14 +3,14 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD = /home/mihnea/envs/n12/bin/sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = /home/mihnea/envs/n12/var/docs/naaya.i18n
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) /home/mihnea/envs/n12/src/naaya.i18n/docs/sphinx
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 
@@ -72,17 +72,17 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/naayai18n.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/naaya-docs.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/naayai18n.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/naaya-docs.qhc"
 
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/naayai18n"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/naayai18n"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/naaya-docs"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/naaya-docs"
 	@echo "# devhelp"
 
 epub:

docs/sphinx/api/index.rst

@@ -0,0 +1,67 @@
+API Documentation
+=================
+
+Portal i18n
+-----------
+
+**Portal i18n** is the main object used for internationalization operations, used
+for querying the other submodules or getting their address. Most
+of the public API available for restricted access resides here.
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    portal_tool
+
+
+Message Catalog
+---------------
+
+The **Message Catalog** is the main storage for translations. Its API is defined
+by *interfaces.INyCatalog* interface.
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    message_catalog/*
+
+
+Negotiator
+---------------
+
+The **Negotiator** is responsible for selecting a display language for the
+browser. It has some configuration settings which can be tweaked by programmers.
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    negotiator/*
+
+
+Property Manager
+----------------
+
+The **Property Manager** takes care of properly setting and returning localized
+values for objects in database.
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    property_manager/*
+
+
+Import Export Tool
+------------------
+
+The **Import Export Tool** provides input-output action
+for **Message Catalog** data.
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    import_export/*

docs/sphinx/api/portal_tool.rst

@@ -0,0 +1,5 @@
+:mod:`naaya.i18n.portal_tool`
+==============================
+
+.. automodule:: naaya.i18n.portal_tool
+    :members:

docs/sphinx/conf.py

@@ -217,3 +217,22 @@
     ('index', 'naayai18n', u'naaya.i18n Documentation',
      [u'Mihnea Simian'], 1)
 ]
+
+### Custom Naaya related handlers ###
+def skip_zope_related_members(app, what, name, obj, skip, options):
+    """
+    Currently skips security related methods added by ClassSecurityInfo.
+    See http://sphinx.pocoo.org/ext/autodoc.html#event-autodoc-skip-member
+
+    """
+    if skip:
+        # do not "redempt" previously skipped members by autodoc
+        return True
+    elif name.endswith('__roles__'):
+        return True
+    else:
+        return False
+
+def setup(app):
+    app.connect('autodoc-skip-member', skip_zope_related_members)
+

docs/sphinx/index.rst

@@ -1,17 +1,13 @@
-.. naaya.i18n documentation master file, created by
-   sphinx-quickstart on Tue Jun 28 16:08:09 2011.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 naaya.i18n's documentation
 ======================================
-**naaya.i18n** is a required dependency module for **Naaya** content management system.
- It is responsible for management of localized data and portal i18n related issues.
- This document refers to version |release|.
+**naaya.i18n** is a required dependency module for **Naaya** content management
+system. It is responsible for management of localized data and portal i18n
+related issues. This document refers to version |release|.
 
 Manager's Guide
 ---------------
-See what you need to know about internationalization if you are a Naaya portal manager.
+See what you need to know about internationalization if you are a Naaya
+portal manager.
 
 .. toctree::
     :maxdepth: 2

docs/sphinx/manager_guide/manage_languages.rst

@@ -17,9 +17,9 @@ Selecting the default language
 The *default language* is the language the portal is first displayed in,
 when the user either has no localization preferences set or the default
 language is within his preferred languages. This is also the default fallback
- language.
+language.
 
 This setting does not influence the default translation for new found strings.
- Each new found message without translation is still considered English,
- since most of the Naaya and Zope products are edited so.
+Each new found message without translation is still considered English,
+since most of the Naaya and Zope products are edited so.
 

naaya/i18n/ExternalService.py

@@ -8,7 +8,7 @@
 from urllib import urlencode
 import re
 
-DUMMY_TEXT = "'XXXXX'" # google tends to change other wildcards like ${}
+DUMMY_TEXT = "XXXXX" # google tends to change other wildcards like ${}
 REQUEST_URI = 'http://translate.google.com/translate_a/t'
 
 def external_translate(message, target_lang):
@@ -21,6 +21,12 @@ def external_translate(message, target_lang):
 
     """
     try:
+        # Replace mappings, if any
+        mappings_pat = re.compile(r'\$\{(.*?)\}')
+        mappings = mappings_pat.findall(message)
+        if mappings is not []:
+            message = mappings_pat.sub(DUMMY_TEXT, message)
+
         op = urllib2.build_opener()
         op.addheaders = [('User-agent', 'Mozilla/5.0')]
         handler = op.open(REQUEST_URI,
@@ -31,16 +37,11 @@ def external_translate(message, target_lang):
         jsonize_pat = re.compile(',,')
         while jsonize_pat.search(body) is not None:
             body = jsonize_pat.sub(r',"",', body)
-        # Replace mappings, if any
-        mappings_pat = re.compile(r'\$\{(.*?)\}')
-        mappings = mappings_pat.findall(body)
-        if mappings is not []:
-            mappings_pat.sub(DUMMY_TEXT, body)
 
         json_data = json.loads(body)
 
         try:
-            translation = json_data[0][0][0]
+            translation = ''.join([ x[0] for x in json_data[0] ])
         except KeyError:
             # no translation or unexpected response
             return ''

naaya/i18n/NyMessageCatalog.py

@@ -2,7 +2,12 @@
 # Python imports
 
 # Zope imports
-from Globals import PersistentMapping
+try:
+    # zope 2.12
+    from Persistence import PersistentMapping
+except ImportError:
+    # zope <= 2.11
+    from Globals import PersistentMapping
 from Persistence import Persistent
 from zope.interface import implements
 

naaya/i18n/TranslationsToolWrapper.py

@@ -15,7 +15,6 @@
 from Acquisition import Implicit
 
 # Product imports
-from portal_tool import message_encode, message_decode
 from LanguageManagers import NyLanguages
 
 class TranslationsToolWrapper(Implicit):
@@ -41,7 +40,7 @@ def msgEncode(self, message):
         Encodes a message in order to be passed as parameter in
         the query string.
         """
-        return quote(message_encode(message))
+        return quote(self.portal_i18n.message_encode(message))
 
     security.declarePublic('message_encode')
     @deprecate(("Portal Translations/message_encode is deprecated, use "

naaya/i18n/patches.py

@@ -8,11 +8,11 @@
 from zope.component import adapts
 from zope.publisher.interfaces import IRequest
 from ZPublisher.BaseRequest import DefaultPublishTraverse
-import zope.thread
 
 # Naaya imports
 from Products.Naaya.interfaces import INySite
 
+
 class NySitePublishTraverse(DefaultPublishTraverse):
     adapts(INySite, IRequest)