Rename "intl" module to "gettext", to make it easier to find. Distinguish environments with different versioning methods and always give the gettext builder its own doctree dir.

doc/Makefile

@@ -8,8 +8,9 @@ PAPER        =
 
 PAPEROPT_a4      = -D latex_paper_size=a4
 PAPEROPT_letter  = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
-                $(SPHINXOPTS) $(O) .
+ALLSPHINXOPTS    = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
+                   $(SPHINXOPTS) $(O) .
+I18NSPHINXOPTS   = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) .
 
 .PHONY: help clean html dirhtml singlehtml text man pickle json htmlhelp \
 	qthelp devhelp epub latex latexpdf changes linkcheck doctest
@@ -116,7 +117,7 @@ latexpdf:
 	@echo "pdflatex finished; the PDF files are in _build/latex."
 
 gettext:
-	$(SPHINXBUILD) -b gettext $(ALLSPHINXOPTS) _build/locale
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) _build/locale
 	@echo
 	@echo "Build finished. The message catalogs are in _build/locale."
 

doc/builders.rst

@@ -240,7 +240,7 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf
 
    .. versionadded:: 0.5
 
-.. module:: sphinx.builders.intl
+.. module:: sphinx.builders.gettext
 .. class:: MessageCatalogBuilder
 
    This builder produces gettext-style message catalos.  Each top-level file or

doc/intl.rst

@@ -32,7 +32,7 @@ task to split up paragraphs which are too large as there is no sane automated
 way to do that.
 
 After Sphinx successfully ran the
-:class:`~sphinx.builders.intl.MessageCatalogBuilder` you will find a collection
+:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a collection
 of ``.pot`` files in your output directory.  These are **catalog templates**
 and contain messages in your original language *only*.
 

sphinx/builders/__init__.py

@@ -31,9 +31,12 @@ class Builder(object):
     name = ''
     # builder's output format, or '' if no document output is produced
     format = ''
+    # doctree versioning method
+    versioning_method = 'none'
 
     def __init__(self, app):
         self.env = app.env
+        self.env.set_versioning_method(self.versioning_method)
         self.srcdir = app.srcdir
         self.confdir = app.confdir
         self.outdir = app.outdir
@@ -330,5 +333,5 @@ BUILTIN_BUILDERS = {
     'changes':    ('changes', 'ChangesBuilder'),
     'linkcheck':  ('linkcheck', 'CheckExternalLinksBuilder'),
     'websupport': ('websupport', 'WebSupportBuilder'),
-    'gettext':    ('intl', 'MessageCatalogBuilder'),
+    'gettext':    ('gettext', 'MessageCatalogBuilder'),
 }

sphinx/builders/gettext.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """
-    sphinx.builders.intl
-    ~~~~~~~~~~~~~~~~~~~~
+    sphinx.builders.gettext
+    ~~~~~~~~~~~~~~~~~~~~~~~
 
     The MessageCatalogBuilder class.
 
@@ -48,6 +48,7 @@ class I18nBuilder(Builder):
     General i18n builder.
     """
     name = 'i18n'
+    versioning_method = 'text'
 
     def init(self):
         Builder.init(self)

sphinx/builders/websupport.py

@@ -26,6 +26,7 @@ class WebSupportBuilder(PickleHTMLBuilder):
     Builds documents for the web support package.
     """
     name = 'websupport'
+    versioning_method = 'commentable'
 
     def init(self):
         PickleHTMLBuilder.init(self)

sphinx/environment.py

@@ -43,6 +43,7 @@ from sphinx.util.nodes import clean_astext, make_refnode, extract_messages
 from sphinx.util.osutil import movefile, SEP, ustrftime
 from sphinx.util.matching import compile_matchers
 from sphinx.util.pycompat import all, class_types
+from sphinx.util.websupport import is_commentable
 from sphinx.errors import SphinxError, ExtensionError
 from sphinx.locale import _, init as init_locale
 from sphinx.versioning import add_uids, merge_doctrees
@@ -79,6 +80,12 @@ default_substitutions = set([
 
 dummy_reporter = Reporter('', 4, 4)
 
+versioning_methods = {
+    'none': False,
+    'text': nodes.TextElement,
+    'commentable': is_commentable,
+}
+
 
 class WarningStream(object):
     def __init__(self, warnfunc):
@@ -313,6 +320,9 @@ class BuildEnvironment:
         self.srcdir = srcdir
         self.config = config
 
+        # the method of doctree versioning; see set_versioning_method
+        self.versioning_method = None
+
         # the application object; only set while update() runs
         self.app = None
 
@@ -380,6 +390,23 @@ class BuildEnvironment:
         self._warnfunc = func
         self.settings['warning_stream'] = WarningStream(func)
 
+    def set_versioning_method(self, method):
+        """This sets the doctree versioning method for this environment.
+
+        Versioning methods are a builder property; only builders with the same
+        versioning method can share the same doctree directory.  Therefore, we
+        raise an exception if the user tries to use an environment with an
+        incompatible versioning method.
+        """
+        if method not in versioning_methods:
+            raise ValueError('invalid versioning method: %r' % method)
+        method = versioning_methods[method]
+        if self.versioning_method not in (None, method):
+            raise SphinxError('This environment is incompatible with the '
+                              'selected builder, please choose another '
+                              'doctree directory.')
+        self.versioning_method = method
+
     def warn(self, docname, msg, lineno=None):
         # strange argument order is due to backwards compatibility
         self._warnfunc(msg, (docname, lineno))
@@ -754,25 +781,24 @@ class BuildEnvironment:
         # store time of build, for outdated files detection
         self.all_docs[docname] = time.time()
 
-        # get old doctree
-        old_doctree_path = self.doc2path(docname, self.doctreedir, '.doctree')
-        try:
-            f = open(old_doctree_path, 'rb')
+        if self.versioning_method:
+            # get old doctree
             try:
-                old_doctree = pickle.load(f)
-            finally:
-                f.close()
-            old_doctree.settings.env = self
-            old_doctree.reporter = Reporter(self.doc2path(docname), 2, 5,
-                                            stream=WarningStream(self._warnfunc))
-        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:
+                old_doctree = None
 
-        # add uids for versioning
-        if old_doctree is None:
-            list(add_uids(doctree, nodes.TextElement))
-        else:
-            list(merge_doctrees(old_doctree, doctree, nodes.TextElement))
+            # add uids for versioning
+            if old_doctree is None:
+                list(add_uids(doctree, nodes.TextElement))
+            else:
+                list(merge_doctrees(
+                    old_doctree, doctree, self.versioning_method))
 
         # make it picklable
         doctree.reporter = None

sphinx/quickstart.py

@@ -361,6 +361,8 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) \
 $(SPHINXOPTS) %(rsrcdir)s
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) %(rsrcdir)s
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp \
 epub latex latexpdf text man changes linkcheck doctest gettext
@@ -483,7 +485,7 @@ info:
 \t@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
 
 gettext:
-\t$(SPHINXBUILD) -b gettext $(ALLSPHINXOPTS) $(BUILDDIR)/locale
+\t$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
 \t@echo
 \t@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
 
@@ -514,8 +516,10 @@ if "%%SPHINXBUILD%%" == "" (
 )
 set BUILDDIR=%(rbuilddir)s
 set ALLSPHINXOPTS=-d %%BUILDDIR%%/doctrees %%SPHINXOPTS%% %(rsrcdir)s
+set I18NSPHINXOPTS=%%SPHINXOPTS%% %(rsrcdir)s
 if NOT "%%PAPER%%" == "" (
 \tset ALLSPHINXOPTS=-D latex_paper_size=%%PAPER%% %%ALLSPHINXOPTS%%
+\tset I18NSPHINXOPTS=-D latex_paper_size=%%PAPER%% %%I18NSPHINXOPTS%%
 )
 
 if "%%1" == "" goto help
@@ -659,7 +663,7 @@ if "%%1" == "texinfo" (
 )
 
 if "%%1" == "gettext" (
-\t%%SPHINXBUILD%% -b gettext %%ALLSPHINXOPTS%% %%BUILDDIR%%/locale
+\t%%SPHINXBUILD%% -b gettext %%I18NSPHINXOPTS%% %%BUILDDIR%%/locale
 \tif errorlevel 1 exit /b 1
 \techo.
 \techo.Build finished. The message catalogs are in %%BUILDDIR%%/locale.
@@ -991,4 +995,3 @@ def main(argv=sys.argv):
         print
         print '[Interrupted.]'
         return
-