Commits

Georg Brandl committed 5a5f4c1

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.

Comments (0)

Files changed (9)

 
 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
 	@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."
 
 
    .. 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
 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

     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
     'changes':    ('changes', 'ChangesBuilder'),
     'linkcheck':  ('linkcheck', 'CheckExternalLinksBuilder'),
     'websupport': ('websupport', 'WebSupportBuilder'),
-    'gettext':    ('intl', 'MessageCatalogBuilder'),
+    'gettext':    ('gettext', 'MessageCatalogBuilder'),
 }

sphinx/builders/gettext.py

+# -*- coding: utf-8 -*-
+"""
+    sphinx.builders.gettext
+    ~~~~~~~~~~~~~~~~~~~~~~~
+
+    The MessageCatalogBuilder class.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from os import path
+from codecs import open
+from datetime import datetime
+from collections import defaultdict
+
+from docutils import nodes
+
+from sphinx.builders import Builder
+from sphinx.util.nodes import extract_messages
+from sphinx.util.osutil import SEP, copyfile
+from sphinx.util.console import darkgreen
+
+POHEADER = ur"""
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) %(copyright)s
+# This file is distributed under the same license as the %(project)s package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: %(version)s\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: %(ctime)s\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+
+"""[1:]
+
+
+class I18nBuilder(Builder):
+    """
+    General i18n builder.
+    """
+    name = 'i18n'
+    versioning_method = 'text'
+
+    def init(self):
+        Builder.init(self)
+        self.catalogs = defaultdict(dict)
+
+    def get_target_uri(self, docname, typ=None):
+        return ''
+
+    def get_outdated_docs(self):
+        return self.env.found_docs
+
+    def prepare_writing(self, docnames):
+        return
+
+    def write_doc(self, docname, doctree):
+        catalog = self.catalogs[docname.split(SEP, 1)[0]]
+
+        for node, msg in extract_messages(doctree):
+            catalog.setdefault(node.uid, msg)
+
+
+class MessageCatalogBuilder(I18nBuilder):
+    """
+    Builds gettext-style message catalogs (.pot files).
+    """
+    name = 'gettext'
+
+    def finish(self):
+        I18nBuilder.finish(self)
+        data = dict(
+            version = self.config.version,
+            copyright = self.config.copyright,
+            project = self.config.project,
+            # XXX should supply tz
+            ctime = datetime.now().strftime('%Y-%m-%d %H:%M%z'),
+        )
+        for section, messages in self.status_iterator(
+                self.catalogs.iteritems(), "writing message catalogs... ",
+                lambda (section, _):darkgreen(section), len(self.catalogs)):
+
+            pofn = path.join(self.outdir, section + '.pot')
+            pofile = open(pofn, 'w', encoding='utf-8')
+            try:
+                pofile.write(POHEADER % data)
+                for uid, message in messages.iteritems():
+                    # message contains *one* line of text ready for translation
+                    message = message.replace(u'\\', ur'\\'). \
+                                      replace(u'"', ur'\"')
+                    pomsg = u'#%s\nmsgid "%s"\nmsgstr ""\n\n' % (uid, message)
+                    pofile.write(pomsg)
+            finally:
+                pofile.close()

sphinx/builders/intl.py

-# -*- coding: utf-8 -*-
-"""
-    sphinx.builders.intl
-    ~~~~~~~~~~~~~~~~~~~~
-
-    The MessageCatalogBuilder class.
-
-    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
-    :license: BSD, see LICENSE for details.
-"""
-
-from os import path
-from codecs import open
-from datetime import datetime
-from collections import defaultdict
-
-from docutils import nodes
-
-from sphinx.builders import Builder
-from sphinx.util.nodes import extract_messages
-from sphinx.util.osutil import SEP, copyfile
-from sphinx.util.console import darkgreen
-
-POHEADER = ur"""
-# SOME DESCRIPTIVE TITLE.
-# Copyright (C) %(copyright)s
-# This file is distributed under the same license as the %(project)s package.
-# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
-#
-#, fuzzy
-msgid ""
-msgstr ""
-"Project-Id-Version: %(version)s\n"
-"Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: %(ctime)s\n"
-"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
-"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
-"Language-Team: LANGUAGE <LL@li.org>\n"
-"MIME-Version: 1.0\n"
-"Content-Type: text/plain; charset=UTF-8\n"
-"Content-Transfer-Encoding: 8bit\n"
-
-"""[1:]
-
-
-class I18nBuilder(Builder):
-    """
-    General i18n builder.
-    """
-    name = 'i18n'
-
-    def init(self):
-        Builder.init(self)
-        self.catalogs = defaultdict(dict)
-
-    def get_target_uri(self, docname, typ=None):
-        return ''
-
-    def get_outdated_docs(self):
-        return self.env.found_docs
-
-    def prepare_writing(self, docnames):
-        return
-
-    def write_doc(self, docname, doctree):
-        catalog = self.catalogs[docname.split(SEP, 1)[0]]
-
-        for node, msg in extract_messages(doctree):
-            catalog.setdefault(node.uid, msg)
-
-
-class MessageCatalogBuilder(I18nBuilder):
-    """
-    Builds gettext-style message catalogs (.pot files).
-    """
-    name = 'gettext'
-
-    def finish(self):
-        I18nBuilder.finish(self)
-        data = dict(
-            version = self.config.version,
-            copyright = self.config.copyright,
-            project = self.config.project,
-            # XXX should supply tz
-            ctime = datetime.now().strftime('%Y-%m-%d %H:%M%z'),
-        )
-        for section, messages in self.status_iterator(
-                self.catalogs.iteritems(), "writing message catalogs... ",
-                lambda (section, _):darkgreen(section), len(self.catalogs)):
-
-            pofn = path.join(self.outdir, section + '.pot')
-            pofile = open(pofn, 'w', encoding='utf-8')
-            try:
-                pofile.write(POHEADER % data)
-                for uid, message in messages.iteritems():
-                    # message contains *one* line of text ready for translation
-                    message = message.replace(u'\\', ur'\\'). \
-                                      replace(u'"', ur'\"')
-                    pomsg = u'#%s\nmsgid "%s"\nmsgstr ""\n\n' % (uid, message)
-                    pofile.write(pomsg)
-            finally:
-                pofile.close()

sphinx/builders/websupport.py

     Builds documents for the web support package.
     """
     name = 'websupport'
+    versioning_method = 'commentable'
 
     def init(self):
         PickleHTMLBuilder.init(self)

sphinx/environment.py

 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
 
 dummy_reporter = Reporter('', 4, 4)
 
+versioning_methods = {
+    'none': False,
+    'text': nodes.TextElement,
+    'commentable': is_commentable,
+}
+
 
 class WarningStream(object):
     def __init__(self, warnfunc):
         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
 
         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))
         # 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

 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
 \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."
 
 )
 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
 )
 
 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.
         print
         print '[Interrupted.]'
         return
-
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.