Merged in Ivoz/sphinx (pull request #186)

Add extension of included README (.rst)

23 files changed, 263 insertions, 50 deletions

diff --git a/CHANGES b/CHANGES
index 0e9717dd..c15cd0b9 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,6 +1,10 @@
-Release 1.2 (in development)
+Release 1.3 (in development)
 ============================
 
+
+Release 1.2 (released Dec 10, 2013)
+===================================
+
 Features added
 --------------
 
@@ -18,10 +22,26 @@ Bugs fixed
 
 * Restore ``versionmodified`` CSS class for versionadded/changed and deprecated
   directives.
+* Fix: `html_theme_path=['.']` is a trigger of rebuild all documents always
+  (This change keeps the current "theme changes cause a rebuild" feature).
 
 * #1296: Fix invalid charset in HTML help generated HTML files for default
   locale.
 
+* PR#190: Fix gettext does not extract figure caption and rubric title inside
+  other blocks. Thanks to Michael Schlenker.
+
+* PR#176: Make sure setup_command test can always import Sphinx. Thanks to
+  Dmitry Shachnev.
+
+* #1311: Fix test_linkcode.test_html fails with C locale and Python 3.
+
+* #1269: Fix ResourceWarnings with Python 3.2 or later.
+
+* #1138: Fix: When ``autodoc_docstring_signature = True`` and
+  ``autoclass_content = 'init'`` or ``'both'``, __init__ line should be
+  removed from class documentation.
+
 
 Release 1.2 beta3 (released Oct 3, 2013)
 ========================================
diff --git a/doc/domains.rst b/doc/domains.rst
index 56642887..57b10c3b 100644
--- a/doc/domains.rst
+++ b/doc/domains.rst
@@ -168,7 +168,7 @@ The following directives are provided for module and class contents:
    Describes an exception class.  The signature can, but need not include
    parentheses with constructor arguments.
 
-.. rst:directive:: .. py:function:: name(signature)
+.. rst:directive:: .. py:function:: name(parameters)
 
    Describes a module-level function.  The signature should include the
    parameters, enclosing optional parameters in brackets.  Default values can be
@@ -186,10 +186,11 @@ The following directives are provided for module and class contents:
    are modified), side effects, and possible exceptions.  A small example may be
    provided.
 
-.. rst:directive:: .. py:class:: name[(signature)]
+.. rst:directive:: .. py:class:: name
+                   .. py:class:: name(parameters)
 
-   Describes a class.  The signature can include parentheses with parameters
-   which will be shown as the constructor arguments.  See also
+   Describes a class.  The signature can optionally include parentheses with
+   parameters which will be shown as the constructor arguments.  See also
    :ref:`signatures`.
 
    Methods and attributes belonging to the class should be placed in this
@@ -213,26 +214,26 @@ The following directives are provided for module and class contents:
    information about the type of the data to be expected and whether it may be
    changed directly.
 
-.. rst:directive:: .. py:method:: name(signature)
+.. rst:directive:: .. py:method:: name(parameters)
 
    Describes an object method.  The parameters should not include the ``self``
    parameter.  The description should include similar information to that
    described for ``function``.  See also :ref:`signatures`.
 
-.. rst:directive:: .. py:staticmethod:: name(signature)
+.. rst:directive:: .. py:staticmethod:: name(parameters)
 
    Like :rst:dir:`py:method`, but indicates that the method is a static method.
 
    .. versionadded:: 0.4
 
-.. rst:directive:: .. py:classmethod:: name(signature)
+.. rst:directive:: .. py:classmethod:: name(parameters)
 
    Like :rst:dir:`py:method`, but indicates that the method is a class method.
 
    .. versionadded:: 0.6
 
 .. rst:directive:: .. py:decorator:: name
-                   .. py:decorator:: name(signature)
+                   .. py:decorator:: name(parameters)
 
    Describes a decorator function.  The signature should *not* represent the
    signature of the actual function, but the usage as a decorator.  For example,
@@ -260,6 +261,8 @@ The following directives are provided for module and class contents:
 
          Set name of the decorated function to *name*.
 
+   (as opposed to ``.. py:decorator:: removename(func)``.)
+
    There is no ``py:deco`` role to link to a decorator that is marked up with
    this directive; rather, use the :rst:role:`py:func` role.
 
diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index 10ba491e..98ce5621 100644
--- a/doc/markup/misc.rst
+++ b/doc/markup/misc.rst
@@ -212,9 +212,9 @@ following directive exists:
    ``p{width}`` construct, or tabulary's automatic specifiers:
 
    +-----+------------------------------------------+
-   |``L``| ragged-left column with automatic width  |
+   |``L``| flush left column with automatic width   |
    +-----+------------------------------------------+
-   |``R``| ragged-right column with automatic width |
+   |``R``| flush right column with automatic width  |
    +-----+------------------------------------------+
    |``C``| centered column with automatic width     |
    +-----+------------------------------------------+
diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst
index c17fb9b0..41c265f8 100644
--- a/doc/markup/toctree.rst
+++ b/doc/markup/toctree.rst
@@ -141,9 +141,8 @@ tables of contents.  The ``toctree`` directive is the central element.
    In the end, all documents in the :term:`source directory` (or subdirectories)
    must occur in some ``toctree`` directive; Sphinx will emit a warning if it
    finds a file that is not included, because that means that this file will not
-   be reachable through standard navigation.  Use :confval:`unused_docs` to
-   explicitly exclude documents from building, and :confval:`exclude_trees` to
-   exclude whole directories.
+   be reachable through standard navigation.  Use :confval:`exclude_patterns` to
+   explicitly exclude documents or directories from building.
 
    The "master document" (selected by :confval:`master_doc`) is the "root" of
    the TOC tree hierarchy.  It can be used as the documentation's main page, or
diff --git a/sphinx/__init__.py b/sphinx/__init__.py
index 0f45ecb0..f93e57a1 100644
--- a/sphinx/__init__.py
+++ b/sphinx/__init__.py
@@ -15,11 +15,12 @@
 import sys
 from os import path
 
-__version__  = '1.2b3'
-__released__ = '1.2b3'  # used when Sphinx builds its own docs
+__version__  = '1.3a0'
+__released__ = '1.3a0'  # used when Sphinx builds its own docs
 # version info for better programmatic use
 # possible values for 3rd element: 'alpha', 'beta', 'rc', 'final'
-version_info = (1, 2, 0, 'beta', 3)
+# 'final' has 0 as the last element
+version_info = (1, 3, 0, 'alpha', 0)
 
 package_dir = path.abspath(path.dirname(__file__))
 
diff --git a/sphinx/builders/gettext.py b/sphinx/builders/gettext.py
index 50d5163b..f648c311 100644
--- a/sphinx/builders/gettext.py
+++ b/sphinx/builders/gettext.py
@@ -9,6 +9,8 @@
     :license: BSD, see LICENSE for details.
 """
 
+from __future__ import with_statement
+
 from os import path, walk
 from codecs import open
 from time import time
@@ -160,7 +162,8 @@ class MessageCatalogBuilder(I18nBuilder):
 
         for template in self.status_iterator(files,
                 'reading templates... ', purple, len(files)):
-            context = open(template, 'r', encoding='utf-8').read()
+            with open(template, 'r', encoding='utf-8') as f:
+                context = f.read()
             for line, meth, msg in extract_translations(context):
                 origin = MsgOrigin(template, line)
                 self.catalogs['sphinx'].add(msg, origin)
diff --git a/sphinx/environment.py b/sphinx/environment.py
index 3c9c830c..919ae710 100644
--- a/sphinx/environment.py
+++ b/sphinx/environment.py
@@ -1489,6 +1489,10 @@ class BuildEnvironment:
         new = {}
 
         def add_entry(word, subword, link=True, dic=new):
+            # Force the word to be unicode if it's a ASCII bytestring.
+            # This will solve problems with unicode normalization later.
+            # For instance the RFC role will add bytestrings at the moment
+            word = unicode(word)
             entry = dic.get(word)
             if not entry:
                 dic[word] = entry = [[], {}]
diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py
index 348c072c..8d78feb2 100644
--- a/sphinx/ext/autodoc.py
+++ b/sphinx/ext/autodoc.py
@@ -28,7 +28,7 @@ from sphinx.application import ExtensionError
 from sphinx.util.nodes import nested_parse_with_titles
 from sphinx.util.compat import Directive
 from sphinx.util.inspect import getargspec, isdescriptor, safe_getmembers, \
-     safe_getattr, safe_repr
+     safe_getattr, safe_repr, is_builtin_class_method
 from sphinx.util.pycompat import base_exception, class_types
 from sphinx.util.docstrings import prepare_docstring
 
@@ -957,6 +957,10 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):
         try:
             argspec = getargspec(self.object)
         except TypeError:
+            if (is_builtin_class_method(self.object, '__new__') and
+               is_builtin_class_method(self.object, '__init__')):
+                raise TypeError('%r is a builtin class' % self.object)
+
             # if a class should be documented as function (yay duck
             # typing) we try to use the constructor signature as function
             # signature without the first argument.
@@ -1009,8 +1013,9 @@ class ClassDocumenter(ModuleLevelDocumenter):
         initmeth = self.get_attr(self.object, '__init__', None)
         # classes without __init__ method, default __init__ or
         # __init__ written in C?
-        if initmeth is None or initmeth is object.__init__ or not \
-               (inspect.ismethod(initmeth) or inspect.isfunction(initmeth)):
+        if initmeth is None or \
+               is_builtin_class_method(self.object, '__init__') or \
+               not(inspect.ismethod(initmeth) or inspect.isfunction(initmeth)):
             return None
         try:
             argspec = getargspec(initmeth)
@@ -1066,8 +1071,18 @@ class ClassDocumenter(ModuleLevelDocumenter):
         # for classes, what the "docstring" is can be controlled via a
         # config value; the default is only the class docstring
         if content in ('both', 'init'):
-            initdocstring = self.get_attr(
-                self.get_attr(self.object, '__init__', None), '__doc__')
+            # get __init__ method document from __init__.__doc__
+            if self.env.config.autodoc_docstring_signature:
+                # only act if the feature is enabled
+                init_doc = MethodDocumenter(self.directive, '__init__')
+                init_doc.object = self.get_attr(self.object, '__init__', None)
+                init_doc.objpath = ['__init__']
+                init_doc._find_signature()  # this effects to get_doc() result
+                initdocstring = '\n'.join(
+                    ['\n'.join(l) for l in init_doc.get_doc(encoding)])
+            else:
+                initdocstring = self.get_attr(
+                    self.get_attr(self.object, '__init__', None), '__doc__')
             # for new-style classes, no __init__ means default __init__
             if initdocstring == object.__init__.__doc__:
                 initdocstring = None
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
index f5c5a884..a73e79f5 100644
--- a/sphinx/ext/autosummary/__init__.py
+++ b/sphinx/ext/autosummary/__init__.py
@@ -206,8 +206,6 @@ class Autosummary(Directive):
             docnames = []
             for name, sig, summary, real_name in items:
                 docname = posixpath.join(tree_prefix, real_name)
-                if docname.endswith(suffix):
-                    docname = docname[:-len(suffix)]
                 docname = posixpath.normpath(posixpath.join(dirname, docname))
                 if docname not in env.found_docs:
                     self.warn('toctree references unknown document %r'
diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py
index 20d92a32..300cfef6 100644
--- a/sphinx/jinja2glue.py
+++ b/sphinx/jinja2glue.py
@@ -91,25 +91,27 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader):
         # create a chain of paths to search
         if theme:
             # the theme's own dir and its bases' dirs
-            chain = theme.get_dirchain()
+            pathchain = theme.get_dirchain()
             # then the theme parent paths
-            chain.extend(theme.themepath)
+            loaderchain = pathchain + theme.themepath
         elif dirs:
-            chain = list(dirs)
+            pathchain = loaderchain = list(dirs)
         else:
-            chain = []
+            pathchain = loaderchain = []
 
         # prepend explicit template paths
         self.templatepathlen = len(builder.config.templates_path)
         if builder.config.templates_path:
-            chain[0:0] = [path.join(builder.confdir, tp)
-                          for tp in builder.config.templates_path]
+            cfg_templates_path = [path.join(builder.confdir, tp)
+                                  for tp in builder.config.templates_path]
+            pathchain[0:0] = cfg_templates_path
+            loaderchain[0:0] = cfg_templates_path
 
         # store it for use in newest_template_mtime
-        self.pathchain = chain
+        self.pathchain = pathchain
 
         # make the paths into loaders
-        self.loaders = map(SphinxFileSystemLoader, chain)
+        self.loaders = map(SphinxFileSystemLoader, loaderchain)
 
         use_i18n = builder.app.translator is not None
         extensions = use_i18n and ['jinja2.ext.i18n'] or []
diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty
index 9b083cc6..50c0d16a 100644
--- a/sphinx/texinputs/sphinx.sty
+++ b/sphinx/texinputs/sphinx.sty
@@ -508,13 +508,11 @@
   }
 \fi
 
-% do not use \@chappos in Appendix in pTeX
+% disable \@chappos in Appendix in pTeX
 \ifx\kanjiskip\undefined\else
-  \renewcommand{\appendix}{\par
-    \setcounter{chapter}{0}
-      \setcounter{section}{0}
-      \gdef\@chapapp{\appendixname}
-      \gdef\@chappos{}
-      \gdef\thechapter{\@Alph\c@chapter}
+  \let\py@OldAppendix=\appendix
+  \renewcommand{\appendix}{
+    \py@OldAppendix
+    \gdef\@chappos{}
   }
 \fi
diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py
index 4c337ef9..61061a9a 100644
--- a/sphinx/util/inspect.py
+++ b/sphinx/util/inspect.py
@@ -137,3 +137,20 @@ def safe_repr(object):
     if isinstance(s, bytes):
         return force_decode(s, None).replace('\n', ' ')
     return s.replace('\n', ' ')
+
+
+def is_builtin_class_method(obj, attr_name):
+    """If attr_name is implemented at builtin class, return True.
+
+        >>> is_builtin_class_method(int, '__init__')
+        True
+
+    Why this function needed? CPython implements int.__init__ by Descriptor
+    but PyPy implements it by pure Python code.
+    """
+    classes = [c for c in inspect.getmro(obj) if attr_name in c.__dict__]
+    cls = classes[0] if classes else object
+
+    if not hasattr(__builtins__, cls.__name__):
+        return False
+    return getattr(__builtins__, cls.__name__) is cls
diff --git a/sphinx/util/nodes.py b/sphinx/util/nodes.py
index a8395f60..da9b4be6 100644
--- a/sphinx/util/nodes.py
+++ b/sphinx/util/nodes.py
@@ -58,8 +58,8 @@ def extract_messages(doctree):
         # this issue was filed to Docutils tracker:
         # sf.net/tracker/?func=detail&aid=3599485&group_id=38414&atid=422032
         # sourceforge.net/p/docutils/patches/108/
-        if isinstance(node, (nodes.caption, nodes.title)) and not node.source:
-            node.source = node.parent.source
+        if isinstance(node, (nodes.caption, nodes.title, nodes.rubric)) and not node.source:
+            node.source = find_source_node(node)
             node.line = 0  #need fix docutils to get `node.line`
 
         if not node.source:
@@ -77,6 +77,18 @@ def extract_messages(doctree):
             yield node, msg
 
 
+def find_source_node(node):
+    for pnode in traverse_parent(node):
+        if pnode.source:
+            return pnode.source
+
+
+def traverse_parent(node):
+    while node:
+        yield node
+        node = node.parent
+
+
 def traverse_translatable_index(doctree):
     """Traverse translatable index node from a document tree."""
     def is_block_index(node):
diff --git a/tests/roots/test-intl/figure_caption.po b/tests/roots/test-intl/figure_caption.po
index 01b4c041..2b85aea3 100644
--- a/tests/roots/test-intl/figure_caption.po
+++ b/tests/roots/test-intl/figure_caption.po
@@ -27,3 +27,9 @@ msgstr "MY DESCRIPTION PARAGRAPH1 OF THE FIGURE."
 

 msgid "My description paragraph2 of the figure."

 msgstr "MY DESCRIPTION PARAGRAPH2 OF THE FIGURE."

+

+msgid "figure in the block"

+msgstr "FIGURE IN THE BLOCK"

+

+msgid "block"

+msgstr "BLOCK"

diff --git a/tests/roots/test-intl/figure_caption.txt b/tests/roots/test-intl/figure_caption.txt
index 75567b3a..0f978b55 100644
--- a/tests/roots/test-intl/figure_caption.txt
+++ b/tests/roots/test-intl/figure_caption.txt
@@ -10,3 +10,17 @@ i18n with figure caption
    My description paragraph1 of the figure.
 
    My description paragraph2 of the figure.
+
+figure in the block
+---------------------
+
+block
+
+   .. figure:: i18n.png
+
+      My caption of the figure
+
+      My description paragraph1 of the figure.
+
+      My description paragraph2 of the figure.
+
diff --git a/tests/roots/test-intl/rubric.po b/tests/roots/test-intl/rubric.po
new file mode 100644
index 00000000..2c1214b7
--- /dev/null
+++ b/tests/roots/test-intl/rubric.po
@@ -0,0 +1,29 @@
+# SOME DESCRIPTIVE TITLE.

+# Copyright (C) 2012, foof

+# This file is distributed under the same license as the foo package.

+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

+#

+#, fuzzy

+msgid ""

+msgstr ""

+"Project-Id-Version: sphinx 1.0\n"

+"Report-Msgid-Bugs-To: \n"

+"POT-Creation-Date: 2013-11-12 7:00\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"

+

+msgid "i18n with rubric"

+msgstr "I18N WITH RUBRIC"

+

+msgid "rubric title"

+msgstr "RUBRIC TITLE"

+

+msgid "rubric in the block"

+msgstr "RUBRIC IN THE BLOCK"

+

+msgid "block"

+msgstr "BLOCK"

diff --git a/tests/roots/test-intl/rubric.txt b/tests/roots/test-intl/rubric.txt
new file mode 100644
index 00000000..f285d49c
--- /dev/null
+++ b/tests/roots/test-intl/rubric.txt
@@ -0,0 +1,14 @@
+:tocdepth: 2
+
+i18n with rubric
+================
+
+.. rubric:: rubric title
+
+rubric in the block
+-------------------
+
+block
+
+   .. rubric:: rubric title
+
diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py
index 1931c0d0..63c341f1 100644
--- a/tests/test_autodoc.py
+++ b/tests/test_autodoc.py
@@ -301,6 +301,39 @@ def test_get_doc():
     assert getdocl('class', D) == ['Class docstring', '', 'Init docstring',
                                    '', 'Other', ' lines']
 
+    #__init__ have signature at first line of docstring
+    class E:
+        """Class docstring"""
+        def __init__(self, *args, **kw):
+            """
+            __init__(a1, a2, kw1=True, kw2=False)
+
+            Init docstring
+            """
+
+    # signature line in the docstring will be kept when
+    # autodoc_docstring_signature == False
+    directive.env.config.autodoc_docstring_signature = False
+    directive.env.config.autoclass_content = 'class'
+    assert getdocl('class', E) == ['Class docstring']
+    directive.env.config.autoclass_content = 'init'
+    assert getdocl('class', E) == ['__init__(a1, a2, kw1=True, kw2=False)',
+                                   '', 'Init docstring']
+    directive.env.config.autoclass_content = 'both'
+    assert getdocl('class', E) == ['Class docstring', '',
+                                   '__init__(a1, a2, kw1=True, kw2=False)',
+                                   '', 'Init docstring']
+
+    # signature line in the docstring will be removed when
+    # autodoc_docstring_signature == True
+    directive.env.config.autodoc_docstring_signature = True  #default
+    directive.env.config.autoclass_content = 'class'
+    assert getdocl('class', E) == ['Class docstring']
+    directive.env.config.autoclass_content = 'init'
+    assert getdocl('class', E) == ['Init docstring']
+    directive.env.config.autoclass_content = 'both'
+    assert getdocl('class', E) == ['Class docstring', '', 'Init docstring']
+
 
 @with_setup(setup_test)
 def test_docstring_processing():
diff --git a/tests/test_build_html.py b/tests/test_build_html.py
index aef73305..d5b59e42 100644
--- a/tests/test_build_html.py
+++ b/tests/test_build_html.py
@@ -365,7 +365,7 @@ def test_html(app):
           confoverrides={'html_sidebars': {'*': ['globaltoc.html']}},
           )
 def test_html_with_globaltoc_and_hidden_toctree(app):
-    # issue #1157: combination of 'globaltoc.html' and hidden toctree cause 
+    # issue #1157: combination of 'globaltoc.html' and hidden toctree cause
     # exception.
     (app.srcdir / 'contents.rst').write_text(
             '\n.. toctree::'
diff --git a/tests/test_intl.py b/tests/test_intl.py
index 405ccd39..c9822089 100644
--- a/tests/test_intl.py
+++ b/tests/test_intl.py
@@ -514,7 +514,31 @@ def test_i18n_figure_caption(app):
               u"\n************************\n"
               u"\n   [image]MY CAPTION OF THE FIGURE\n"
               u"\n   MY DESCRIPTION PARAGRAPH1 OF THE FIGURE.\n"
-              u"\n   MY DESCRIPTION PARAGRAPH2 OF THE FIGURE.\n")
+              u"\n   MY DESCRIPTION PARAGRAPH2 OF THE FIGURE.\n"
+              u"\n"
+              u"\nFIGURE IN THE BLOCK"
+              u"\n===================\n"
+              u"\nBLOCK\n"
+              u"\n      [image]MY CAPTION OF THE FIGURE\n"
+              u"\n      MY DESCRIPTION PARAGRAPH1 OF THE FIGURE.\n"
+              u"\n      MY DESCRIPTION PARAGRAPH2 OF THE FIGURE.\n")
+
+    assert result == expect
+
+
+@with_intl_app(buildername='text')
+def test_i18n_rubric(app):
+    # regression test for pull request #190
+    app.builder.build(['rubric'])
+    result = (app.outdir / 'rubric.txt').text(encoding='utf-8')
+    expect = (u"\nI18N WITH RUBRIC"
+              u"\n****************\n"
+              u"\n-[ RUBRIC TITLE ]-\n"
+              u"\n"
+              u"\nRUBRIC IN THE BLOCK"
+              u"\n===================\n"
+              u"\nBLOCK\n"
+              u"\n   -[ RUBRIC TITLE ]-\n")
 
     assert result == expect
 
diff --git a/tests/test_linkcode.py b/tests/test_linkcode.py
index 507cd9ce..190c3bf2 100644
--- a/tests/test_linkcode.py
+++ b/tests/test_linkcode.py
@@ -12,15 +12,12 @@
 import os
 from util import with_app
 
+
 @with_app(srcdir='(temp)', buildername='html', tags=['test_linkcode'])
 def test_html(app):
     app.builder.build_all()
 
-    fp = open(os.path.join(app.outdir, 'objects.html'), 'r')
-    try:
-        stuff = fp.read()
-    finally:
-        fp.close()
+    stuff = (app.outdir / 'objects.html').text(encoding='utf-8')
 
     assert 'http://foobar/source/foolib.py' in stuff
     assert 'http://foobar/js/' in stuff
diff --git a/tests/test_setup_command.py b/tests/test_setup_command.py
index af4b75c0..f32d6abc 100644
--- a/tests/test_setup_command.py
+++ b/tests/test_setup_command.py
@@ -14,6 +14,7 @@ import sys
 import subprocess
 from functools import wraps
 import tempfile
+import sphinx
 
 from util import with_tempdir, test_roots, SkipTest
 from path import path
@@ -35,16 +36,20 @@ def with_setup_command(root, *args, **kwds):
             root.copytree(pkgrootdir)
             cwd = os.getcwd()
             os.chdir(pkgrootdir)
+            pythonpath = os.path.dirname(os.path.dirname(sphinx.__file__))
+            if os.getenv('PYTHONPATH'):
+                pythonpath = os.getenv('PYTHONPATH') + os.pathsep + pythonpath
             command = [sys.executable, 'setup.py', 'build_sphinx']
             command.extend(args)
             try:
                 proc = subprocess.Popen(
                     command,
+                    env=dict(os.environ, PYTHONPATH=pythonpath),
                     stdout=subprocess.PIPE,
                     stderr=subprocess.PIPE)
                 func(pkgrootdir, proc, *args, **kwds)
             finally:
-                tempdir.rmtree()
+                tempdir.rmtree(ignore_errors=True)
                 os.chdir(cwd)
         return deco
     return generator
diff --git a/utils/release-checklist b/utils/release-checklist
new file mode 100644
index 00000000..8ea08bde
--- /dev/null
+++ b/utils/release-checklist
@@ -0,0 +1,19 @@
+Release checklist
+=================
+
+* Check hg status
+* Make check
+* Update version info in sphinx/__init__.py
+* Update release date in CHANGES
+* hg commit
+* make clean
+* python setup.py release bdist_egg sdist upload
+* Check PyPI release page for obvious errors
+* hg tag
+* Merge default into stable if final major release
+* Update homepage (release info), regenerate docs (+printable!)
+* Add new version/milestone to tracker categories
+* Write announcement and send to mailing list/python-announce
+* Update version info, add new CHANGES entry for next version
+* hg commit
+* hg push