Merged in shimizukawa/sphinx (pull request #305)

gettext speed-up. closes #1426

CHANGES

@@ -20,6 +20,10 @@ Incompatible changes
   templates directory.
 * Custom domains should implement the new `Domain.resolve_any_xref`
   method to make the `any` role work properly.
+* gettext builder: gettext doesn't emit uuid information to generated pot files
+  by default. Please set ``True`` to `gettext_uuid` to emit uuid information.
+  Additionally, if the ``python-levenshtein`` 3rd-party package is installed,
+  it will improve the calculation time.
 * gettext builder: disable extracting/apply 'index' node by default. Please set
   'index' to :confval:`gettext_enables` to enable extracting index entries.
 

doc/config.rst

@@ -424,9 +424,17 @@ documentation on :ref:`intl` for details.
 .. confval:: gettext_uuid
 
    If true, Sphinx generates uuid information for version tracking in message
-   catalogs.
+   catalogs. It is used for:
 
-   The default is ``True``.
+   * Add uid line for each msgids in .pot files.
+   * Calculate similarity between new msgids and previously saved old msgids.
+     This calculation takes a long time.
+
+   If you want to accelerate the calculation, you can use
+   ``python-levenshtein`` 3rd-party package written in C by using
+   :command:`pip install python-levenshtein`.
+
+   The default is ``False``.
 
    .. versionadded:: 1.3
 

sphinx/builders/__init__.py

@@ -42,12 +42,14 @@ class Builder(object):
     format = ''
     # doctree versioning method
     versioning_method = 'none'
+    versioning_compare = False
     # allow parallel write_doc() calls
     allow_parallel = False
 
     def __init__(self, app):
         self.env = app.env
-        self.env.set_versioning_method(self.versioning_method)
+        self.env.set_versioning_method(self.versioning_method,
+                                       self.versioning_compare)
         self.srcdir = app.srcdir
         self.confdir = app.confdir
         self.outdir = app.outdir

sphinx/builders/gettext.py

@@ -84,6 +84,11 @@ class I18nBuilder(Builder):
     """
     name = 'i18n'
     versioning_method = 'text'
+    versioning_compare = None  # be set by `gettext_uuid`
+
+    def __init__(self, app):
+        self.versioning_compare = app.env.config.gettext_uuid
+        super(I18nBuilder, self).__init__(app)
 
     def init(self):
         Builder.init(self)

sphinx/builders/websupport.py

@@ -27,6 +27,7 @@ class WebSupportBuilder(PickleHTMLBuilder):
     """
     name = 'websupport'
     versioning_method = 'commentable'
+    versioning_compare = True  # for commentable node's uuid stability.
 
     def init(self):
         PickleHTMLBuilder.init(self)

sphinx/config.py

@@ -209,7 +209,7 @@ class Config(object):
         # gettext options
         gettext_compact = (True, 'gettext'),
         gettext_location = (True, 'gettext'),
-        gettext_uuid = (True, 'gettext'),
+        gettext_uuid = (False, 'gettext'),
         gettext_auto_build = (True, 'env'),
         gettext_enables = ([], 'env'),
 

sphinx/environment.py

@@ -194,6 +194,7 @@ class BuildEnvironment:
 
         # the method of doctree versioning; see set_versioning_method
         self.versioning_condition = None
+        self.versioning_compare = None
 
         # the application object; only set while update() runs
         self.app = None
@@ -268,7 +269,7 @@ class BuildEnvironment:
         self._warnfunc = func
         self.settings['warning_stream'] = WarningStream(func)
 
-    def set_versioning_method(self, method):
+    def set_versioning_method(self, method, compare):
         """This sets the doctree versioning method for this environment.
 
         Versioning methods are a builder property; only builders with the same
@@ -284,6 +285,7 @@ class BuildEnvironment:
                               'selected builder, please choose another '
                               'doctree directory.')
         self.versioning_condition = condition
+        self.versioning_compare = compare
 
     def warn(self, docname, msg, lineno=None):
         """Emit a warning.
@@ -777,19 +779,21 @@ class BuildEnvironment:
             time.time(), path.getmtime(self.doc2path(docname)))
 
         if self.versioning_condition:
-            # get old doctree
-            try:
-                f = open(self.doc2path(docname,
-                                       self.doctreedir, '.doctree'), 'rb')
+            old_doctree = None
+            if self.versioning_compare:
+                # get old doctree
                 try:
-                    old_doctree = pickle.load(f)
-                finally:
-                    f.close()
-            except EnvironmentError:
-                old_doctree = None
+                    f = open(self.doc2path(docname,
+                                           self.doctreedir, '.doctree'), 'rb')
+                    try:
+                        old_doctree = pickle.load(f)
+                    finally:
+                        f.close()
+                except EnvironmentError:
+                    pass
 
             # add uids for versioning
-            if old_doctree is None:
+            if not self.versioning_compare or old_doctree is None:
                 list(add_uids(doctree, self.versioning_condition))
             else:
                 list(merge_doctrees(

sphinx/versioning.py

@@ -16,6 +16,11 @@ from itertools import product
 from six import iteritems
 from six.moves import range, zip_longest
 
+try:
+    import Levenshtein
+    IS_SPEEDUP = True
+except ImportError:
+    IS_SPEEDUP = False
 
 # anything below that ratio is considered equal/changed
 VERSIONING_RATIO = 65
@@ -57,6 +62,9 @@ def merge_doctrees(old, new, condition):
         if old_node is None:
             new_nodes.append(new_node)
             continue
+        if not getattr(old_node, 'uid', None):
+            # maybe config.gettext_uuid has been changed.
+            old_node.uid = uuid4().hex
         if new_node is None:
             old_nodes.append(old_node)
             continue
@@ -106,7 +114,11 @@ def get_ratio(old, new):
     """
     if not all([old, new]):
         return VERSIONING_RATIO
-    return levenshtein_distance(old, new) / (len(old) / 100.0)
+
+    if IS_SPEEDUP:
+        return Levenshtein.distance(old, new) / (len(old) / 100.0)
+    else:
+        return levenshtein_distance(old, new) / (len(old) / 100.0)
 
 
 def levenshtein_distance(a, b):