From ee98decec11f4dcdfc115eb4acb7e31ea900dbe5 Mon Sep 17 00:00:00 2001 From: Takayuki Shimizukawa Date: Sun, 5 Oct 2014 21:50:44 +0900 Subject: [PATCH 1/3] Incompatibility. Now :confval:`gettext_uuid` is set False by default. If False, also levenshtein calculation is disabled. refs #1426 --- CHANGES | 2 ++ doc/config.rst | 8 ++++++-- sphinx/builders/__init__.py | 4 +++- sphinx/builders/gettext.py | 5 +++++ sphinx/builders/websupport.py | 1 + sphinx/config.py | 2 +- sphinx/environment.py | 26 +++++++++++++++----------- sphinx/versioning.py | 3 +++ 8 files changed, 36 insertions(+), 15 deletions(-) diff --git a/CHANGES b/CHANGES index 0d7689364..66b98de36 100644 --- a/CHANGES +++ b/CHANGES @@ -20,6 +20,8 @@ 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. * gettext builder: disable extracting/apply 'index' node by default. Please set 'index' to :confval:`gettext_enables` to enable extracting index entries. diff --git a/doc/config.rst b/doc/config.rst index f181e5c52..067a2654a 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -424,9 +424,13 @@ 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 take many time. + + The default is ``False``. .. versionadded:: 1.3 diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 7d1bd9206..64ae2a098 100644 --- a/sphinx/builders/__init__.py +++ b/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 diff --git a/sphinx/builders/gettext.py b/sphinx/builders/gettext.py index 01fa06a6d..1962545d0 100644 --- a/sphinx/builders/gettext.py +++ b/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) diff --git a/sphinx/builders/websupport.py b/sphinx/builders/websupport.py index 619ef6fe0..c3fbdc70d 100644 --- a/sphinx/builders/websupport.py +++ b/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) diff --git a/sphinx/config.py b/sphinx/config.py index 8593a190e..933e509d0 100644 --- a/sphinx/config.py +++ b/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'), diff --git a/sphinx/environment.py b/sphinx/environment.py index d9be0be5f..853623d82 100644 --- a/sphinx/environment.py +++ b/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. @@ -776,19 +778,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( diff --git a/sphinx/versioning.py b/sphinx/versioning.py index 8d34802ef..22ecda60c 100644 --- a/sphinx/versioning.py +++ b/sphinx/versioning.py @@ -57,6 +57,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 From fa30e7b52a2103d07cfeccf9403de4a75ec72184 Mon Sep 17 00:00:00 2001 From: Takayuki Shimizukawa Date: Sun, 5 Oct 2014 22:25:50 +0900 Subject: [PATCH 2/3] If the ``python-levenshtein`` 3rd-party package is installed, it will improve the calculation time. refs #1426. --- CHANGES | 2 ++ doc/config.rst | 4 ++++ sphinx/versioning.py | 11 ++++++++++- 3 files changed, 16 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 66b98de36..ebf8cc08b 100644 --- a/CHANGES +++ b/CHANGES @@ -22,6 +22,8 @@ Incompatible changes 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. diff --git a/doc/config.rst b/doc/config.rst index 067a2654a..c5a572672 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -430,6 +430,10 @@ documentation on :ref:`intl` for details. * Calculate similarity between new msgids and previously saved old msgids. This calculation take many time. + If you need a speed for 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 diff --git a/sphinx/versioning.py b/sphinx/versioning.py index 22ecda60c..1be4d39bc 100644 --- a/sphinx/versioning.py +++ b/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 @@ -109,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): From 90e99572401a99546fd1eb8ee83609f0ddb4ef7a Mon Sep 17 00:00:00 2001 From: Takayuki Shimizukawa Date: Wed, 8 Oct 2014 21:36:33 +0900 Subject: [PATCH 3/3] fix grammar by review --- doc/config.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index c5a572672..0cc0ceba0 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -428,10 +428,10 @@ documentation on :ref:`intl` for details. * Add uid line for each msgids in .pot files. * Calculate similarity between new msgids and previously saved old msgids. - This calculation take many time. + This calculation takes a long time. - If you need a speed for the calculation, you can use ``python-levenshtein`` - 3rd-party package written in C by using + 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``.