From 30fe6d4190303760d98163da983a838a49d3e162 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Thu, 5 Mar 2009 20:25:39 +0100
Subject: [PATCH] Sanitize the Environment.update() method API.

---
 sphinx/builders/__init__.py | 26 ++++++++++++------
 sphinx/environment.py       | 53 ++++++++++++++++++++-----------------
 2 files changed, 47 insertions(+), 32 deletions(-)

diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py
index 7b8a70953..4fafa87d2 100644
--- a/sphinx/builders/__init__.py
+++ b/sphinx/builders/__init__.py
@@ -109,7 +109,7 @@ class Builder(object):
         """
         raise NotImplementedError
 
-    def status_iterator(self, iterable, summary, colorfunc=darkgreen):
+    def status_iterator(self, iterable, length, summary, colorfunc=darkgreen):
         l = -1
         for item in iterable:
             if l == -1:
@@ -120,6 +120,17 @@ class Builder(object):
         if l == 0:
             self.info()
 
+    ## new version with progress info
+    #def status_iterator(self, iterable, length, summary, colorfunc=darkgreen):
+    #    l = 0
+    #    for item in iterable:
+    #        if l == 0:
+    #            self.info(bold(summary))
+    #        l += 1
+    #        self.info('  [%3d%%] %s\n' % (100*l/length, colorfunc(item)),
+    #                  nonl=1)
+    #        yield item
+
     supported_image_types = []
 
     def post_process_images(self, doctree):
@@ -251,12 +262,11 @@ class Builder(object):
         warnings = []
         self.env.set_warnfunc(lambda *args: warnings.append(args))
         self.info(bold('updating environment: '), nonl=1)
-        iterator = self.env.update(self.config, self.srcdir,
-                                   self.doctreedir, self.app)
-        # the first item in the iterator is a summary message
-        self.info(iterator.next())
-        for docname in self.status_iterator(iterator, 'reading sources... ',
-                                            purple):
+        msg, length, iterator = self.env.update(self.config, self.srcdir,
+                                                self.doctreedir, self.app)
+        self.info(msg)
+        for docname in self.status_iterator(iterator, length,
+                                            'reading sources... ', purple):
             updated_docnames.add(docname)
             # nothing further to do, the environment has already
             # done the reading
@@ -327,7 +337,7 @@ class Builder(object):
         # write target files
         warnings = []
         self.env.set_warnfunc(lambda *args: warnings.append(args))
-        for docname in self.status_iterator(sorted(docnames),
+        for docname in self.status_iterator(sorted(docnames), len(docnames),
                                             'writing output... ', darkgreen):
             doctree = self.env.get_and_resolve_doctree(docname, self)
             self.write_doc(docname, doctree)
diff --git a/sphinx/environment.py b/sphinx/environment.py
index 5840d2e29..0884eccad 100644
--- a/sphinx/environment.py
+++ b/sphinx/environment.py
@@ -453,10 +453,13 @@ class BuildEnvironment:
         return added, changed, removed
 
     def update(self, config, srcdir, doctreedir, app=None):
-        """(Re-)read all files new or changed since last update.
-        Yields a summary and then docnames as it processes them.
-        Store all environment docnames in the canonical format
-        (ie using SEP as a separator in place of os.path.sep)."""
+        """
+        (Re-)read all files new or changed since last update.  Returns a
+        summary, the total count of documents to reread and an iterator that
+        yields docnames as it processes them.  Store all environment docnames in
+        the canonical format (ie using SEP as a separator in place of
+        os.path.sep).
+        """
         config_changed = False
         if self.config is None:
             msg = '[new config] '
@@ -482,6 +485,7 @@ class BuildEnvironment:
         self.srcdir = srcdir
         self.doctreedir = doctreedir
         self.find_files(config)
+        self.config = config
 
         added, changed, removed = self.get_outdated_files(config_changed)
 
@@ -492,30 +496,31 @@ class BuildEnvironment:
 
         msg += '%s added, %s changed, %s removed' % (len(added), len(changed),
                                                      len(removed))
-        yield msg
 
-        self.config = config
-        self.app = app
+        def update_generator():
+            self.app = app
 
-        # clear all files no longer present
-        for docname in removed:
+            # clear all files no longer present
+            for docname in removed:
+                if app:
+                    app.emit('env-purge-doc', self, docname)
+                self.clear_doc(docname)
+
+            # read all new and changed files
+            to_read = added | changed
+            for docname in sorted(to_read):
+                yield docname
+                self.read_doc(docname, app=app)
+
+            if config.master_doc not in self.all_docs:
+                self.warn(None, 'master file %s not found' %
+                          self.doc2path(config.master_doc))
+
+            self.app = None
             if app:
-                app.emit('env-purge-doc', self, docname)
-            self.clear_doc(docname)
+                app.emit('env-updated', self)
 
-        # read all new and changed files
-        to_read = added | changed
-        for docname in sorted(to_read):
-            yield docname
-            self.read_doc(docname, app=app)
-
-        if config.master_doc not in self.all_docs:
-            self.warn(None, 'master file %s not found' %
-                      self.doc2path(config.master_doc))
-
-        self.app = None
-        if app:
-            app.emit('env-updated', self)
+        return msg, len(added | changed), update_generator()
 
     def check_dependents(self, already):
         to_rewrite = self.assign_section_numbers()