merge with stable

CHANGES

@@ -127,6 +127,11 @@ Bugs fixed
 
 * #1285: Avoid name clashes between C domain objects and section titles.
 
+* #848: Always take the newest code in incremental rebuilds with the
+  :mod:`sphinx.ext.viewcode` extension.
+
+* #979: Fix exclude handling in ``sphinx-apidoc``.
+
 Documentation
 -------------
 
@@ -378,6 +383,8 @@ Features added
     reference documentation in doc directory provides a ``sphinx.pot`` file with
     message strings from ``doc/_templates/*.html`` when using ``make gettext``.
 
+  - PR#61,#703: Add support for non-ASCII filename handling.
+
 * Other builders:
 
   - Added the Docutils-native XML and pseudo-XML builders.  See

sphinx/apidoc.py

@@ -65,7 +65,7 @@ def write_file(name, text, opts):
 
 def format_heading(level, text):
     """Create a heading of <level> [1, 2 or 3 supported]."""
-    underlining = ['=', '-', '~', ][level-1] * len(text)
+    underlining = ['=', '-', '~', ][level - 1] * len(text)
     return '%s\n%s\n\n' % (text, underlining)
 
 
@@ -173,9 +173,6 @@ def recurse_tree(rootpath, excludes, opts):
     Look for every file in the directory tree and create the corresponding
     ReST files.
     """
-    # use absolute path for root, as relative paths like '../../foo' cause
-    # 'if "/." in root ...' to filter out *all* modules otherwise
-    rootpath = path.normpath(path.abspath(rootpath))
     # check if the base directory is a package and get its name
     if INITPY in os.listdir(rootpath):
         root_package = rootpath.split(path.sep)[-1]
@@ -186,12 +183,10 @@ def recurse_tree(rootpath, excludes, opts):
     toplevels = []
     followlinks = getattr(opts, 'followlinks', False)
     for root, subs, files in os.walk(rootpath, followlinks=followlinks):
-        if is_excluded(root, excludes):
-            del subs[:]
-            continue
-        # document only Python module files
+        # document only Python module files (that aren't excluded)
         py_files = sorted(f for f in files
-                          if path.splitext(f)[1] in PY_SUFFIXES)
+                          if path.splitext(f)[1] in PY_SUFFIXES and
+                          not is_excluded(path.join(root, f), excludes))
         is_pkg = INITPY in py_files
         if is_pkg:
             py_files.remove(INITPY)
@@ -200,8 +195,10 @@ def recurse_tree(rootpath, excludes, opts):
             # only accept non-package at toplevel
             del subs[:]
             continue
-        # remove hidden ('.') and private ('_') directories
-        subs[:] = sorted(sub for sub in subs if sub[0] not in ['.', '_'])
+        # remove hidden ('.') and private ('_') directories, as well as
+        # excluded dirs
+        subs[:] = sorted(sub for sub in subs if sub[0] not in ['.', '_']
+                         and not is_excluded(path.join(root, sub), excludes))
 
         if is_pkg:
             # we are in a package with something to document
@@ -225,47 +222,35 @@ def recurse_tree(rootpath, excludes, opts):
 
 
 def normalize_excludes(rootpath, excludes):
-    """
-    Normalize the excluded directory list:
-    * must be either an absolute path or start with rootpath,
-    * otherwise it is joined with rootpath
-    * with trailing slash
-    """
-    f_excludes = []
-    for exclude in excludes:
-        if not path.isabs(exclude) and not exclude.startswith(rootpath):
-            exclude = path.join(rootpath, exclude)
-        f_excludes.append(path.normpath(exclude) + path.sep)
-    return f_excludes
+    """Normalize the excluded directory list."""
+    return [path.normpath(path.abspath(exclude)) for exclude in excludes]
 
 
 def is_excluded(root, excludes):
-    """
-    Check if the directory is in the exclude list.
+    """Check if the directory is in the exclude list.
 
     Note: by having trailing slashes, we avoid common prefix issues, like
           e.g. an exlude "foo" also accidentally excluding "foobar".
     """
-    sep = path.sep
-    if not root.endswith(sep):
-        root += sep
+    root = path.normpath(root)
     for exclude in excludes:
-        if root.startswith(exclude):
+        if root == exclude:
             return True
     return False
 
 
 def main(argv=sys.argv):
-    """
-    Parse and check the command line arguments.
-    """
+    """Parse and check the command line arguments."""
     parser = optparse.OptionParser(
         usage="""\
-usage: %prog [options] -o <output_path> <module_path> [exclude_paths, ...]
+usage: %prog [options] -o <output_path> <module_path> [exclude_path, ...]
 
 Look recursively in <module_path> for Python modules and packages and create
 one reST file with automodule directives per package in the <output_path>.
 
+The <exclude_path>s can be files and/or directories that will be excluded
+from generation.
+
 Note: By default this script will not overwrite already created files.""")
 
     parser.add_option('-o', '--output-dir', action='store', dest='destdir',
@@ -327,6 +312,7 @@ Note: By default this script will not overwrite already created files.""")
     if not path.isdir(opts.destdir):
         if not opts.dryrun:
             os.makedirs(opts.destdir)
+    rootpath = path.normpath(path.abspath(rootpath))
     excludes = normalize_excludes(rootpath, excludes)
     modules = recurse_tree(rootpath, excludes, opts)
     if opts.full:

sphinx/ext/viewcode.py

@@ -24,17 +24,17 @@ def doctree_read(app, doctree):
 
     def has_tag(modname, fullname, docname):
         entry = env._viewcode_modules.get(modname, None)
-        if entry is None:
-            try:
-                analyzer = ModuleAnalyzer.for_module(modname)
-            except Exception:
-                env._viewcode_modules[modname] = False
-                return
+        try:
+            analyzer = ModuleAnalyzer.for_module(modname)
+        except Exception:
+            env._viewcode_modules[modname] = False
+            return
+        if not isinstance(analyzer.code, unicode):
+            code = analyzer.code.decode(analyzer.encoding)
+        else:
+            code = analyzer.code
+        if entry is None or entry[0] != code:
             analyzer.find_tags()
-            if not isinstance(analyzer.code, unicode):
-                code = analyzer.code.decode(analyzer.encoding)
-            else:
-                code = analyzer.code
             entry = code, analyzer.tags, {}
             env._viewcode_modules[modname] = entry
         elif entry is False:
@@ -142,7 +142,7 @@ def collect_pages(app):
     if not modnames:
         return
 
-    app.builder.info(' _modules/index')
+    app.builder.info(' _modules/index', nonl=True)
     html = ['\n']
     # the stack logic is needed for using nested lists for submodules
     stack = ['']

sphinx/themes/basic/static/doctools.js

@@ -168,6 +168,9 @@ var Documentation = {
     var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
     if (terms.length) {
       var body = $('div.body');
+      if (!body.length) {
+        body = $('body');
+      }
       window.setTimeout(function() {
         $.each(terms, function() {
           body.highlightText(this.toLowerCase(), 'highlighted');