merge with stable

CHANGES

@@ -19,6 +19,37 @@ Release 1.1.3 (in development)
 * PR#36: Make the "bibliography to TOC" fix in LaTeX output specific to
   the document class.
 
+* #695: When the highlight language "python" is specified explicitly,
+  do not try to parse the code to recognize non-Python snippets.
+
+* #859: Fix exception under certain circumstances when not finding
+  appropriate objects to link to.
+
+* #860: Do not crash when encountering invalid doctest examples, just
+  emit a warning.
+
+* #864: Fix crash with some settings of :confval:`modindex_common_prefix`.
+
+* #862: Fix handling of ``-D`` and ``-A`` options on Python 3.
+
+* #851: Recognize and warn about circular toctrees, instead of running
+  into recursion errors.
+
+* #853: Restore compatibility with docutils trunk.
+
+* #852: Fix HtmlHelp index entry links again.
+
+* #854: Fix inheritance_diagram raising attribute errors on builtins.
+
+* #832: Fix crashes when putting comments or lone terms in a glossary.
+
+* #834, #818: Fix HTML help language/encoding mapping for all Sphinx
+  supported languages.
+
+* #844: Fix crashes when dealing with Unicode output in doctest extension.
+
+* #831: Provide ``--project`` flag in setup_command as advertised.
+
 
 Release 1.1.2 (Nov 1, 2011) -- 1.1.1 is a silly version number anyway!
 ======================================================================

doc/ext/math.rst

@@ -24,6 +24,10 @@ The input language for mathematics is LaTeX markup.  This is the de-facto
 standard for plain-text math notation and has the added advantage that no
 further translation is necessary when building LaTeX output.
 
+Keep in mind that when you put math markup in **Python docstrings** read by
+:mod:`autodoc <sphinx.ext.autodoc>`, you either have to double all backslashes,
+or use Python raw strings (``r"raw"``).
+
 :mod:`.mathbase` defines these new markup elements:
 
 .. rst:role:: math

sphinx/builders/changes.py

@@ -11,7 +11,6 @@
 
 import codecs
 from os import path
-from cgi import escape
 
 from sphinx import package_dir
 from sphinx.util import copy_static_entry
@@ -20,6 +19,7 @@
 from sphinx.builders import Builder
 from sphinx.util.osutil import ensuredir, os_path
 from sphinx.util.console import bold
+from sphinx.util.pycompat import htmlescape
 
 
 class ChangesBuilder(Builder):
@@ -115,7 +115,7 @@ def write(self, *ignored):
                   '.. deprecated:: %s' % version]
 
         def hl(no, line):
-            line = '<a name="L%s"> </a>' % no + escape(line)
+            line = '<a name="L%s"> </a>' % no + htmlescape(line)
             for x in hltext:
                 if x in line:
                     line = '<span class="hl">%s</span>' % line
@@ -125,7 +125,10 @@ def hl(no, line):
         self.info(bold('copying source files...'))
         for docname in self.env.all_docs:
             f = codecs.open(self.env.doc2path(docname), 'r', 'latin1')
-            lines = f.readlines()
+            try:
+                lines = f.readlines()
+            finally:
+                f.close()
             targetfn = path.join(self.outdir, 'rst', os_path(docname)) + '.html'
             ensuredir(path.dirname(targetfn))
             f = codecs.open(targetfn, 'w', 'latin1')
@@ -148,7 +151,7 @@ def hl(no, line):
                           self.outdir, self)
 
     def hl(self, text, version):
-        text = escape(text)
+        text = htmlescape(text)
         for directive in ['versionchanged', 'versionadded', 'deprecated']:
             text = text.replace('.. %s:: %s' % (directive, version),
                                 '<b>.. %s:: %s</b>' % (directive, version))

sphinx/builders/htmlhelp.py

@@ -11,14 +11,14 @@
 """
 
 import os
-import cgi
 import codecs
 from os import path
 
 from docutils import nodes
 
 from sphinx import addnodes
 from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.util.pycompat import htmlescape
 
 
 # Project file (*.hhp) template.  'outname' is the file basename (like
@@ -124,20 +124,31 @@
 # See http://msdn.microsoft.com/en-us/library/ms930130.aspx for more.
 chm_locales = {
     # lang:   LCID,  encoding
-    'cs':    (0x405, 'iso8859_2'),
-    'de':    (0x407, 'iso8859_1'),
-    'en':    (0x409, 'iso8859_1'),
-    'es':    (0x40a, 'iso8859_1'),
-    'fi':    (0x40b, 'iso8859_1'),
-    'fr':    (0x40c, 'iso8859_1'),
-    'it':    (0x410, 'iso8859_1'),
+    'ca':    (0x403, 'cp1252'),
+    'cs':    (0x405, 'cp1250'),
+    'da':    (0x406, 'cp1252'),
+    'de':    (0x407, 'cp1252'),
+    'en':    (0x409, 'cp1252'),
+    'es':    (0x40a, 'cp1252'),
+    'et':    (0x425, 'cp1257'),
+    'fa':    (0x429, 'cp1256'),
+    'fi':    (0x40b, 'cp1252'),
+    'fr':    (0x40c, 'cp1252'),
+    'hr':    (0x41a, 'cp1250'),
+    'hu':    (0x40e, 'cp1250'),
+    'it':    (0x410, 'cp1252'),
     'ja':    (0x411, 'cp932'),
+    'ko':    (0x412, 'cp949'),
+    'lt':    (0x427, 'cp1257'),
     'lv':    (0x426, 'cp1257'),
-    'nl':    (0x413, 'iso8859_1'),
-    'pl':    (0x415, 'iso8859_2'),
-    'pt_BR': (0x416, 'iso8859_1'),
+    'nl':    (0x413, 'cp1252'),
+    'pl':    (0x415, 'cp1250'),
+    'pt_BR': (0x416, 'cp1252'),
     'ru':    (0x419, 'cp1251'),
-    'sl':    (0x424, 'iso8859_2'),
+    'sk':    (0x41b, 'cp1250'),
+    'sl':    (0x424, 'cp1250'),
+    'sv':    (0x41d, 'cp1252'),
+    'tr':    (0x41f, 'cp1254'),
     'uk_UA': (0x422, 'cp1251'),
     'zh_CN': (0x804, 'cp936'),
     'zh_TW': (0x404, 'cp950'),
@@ -230,7 +241,7 @@ def write_toc(node, ullevel=0):
                         write_toc(subnode, ullevel)
                 elif isinstance(node, nodes.reference):
                     link = node['refuri']
-                    title = cgi.escape(node.astext()).replace('"','"')
+                    title = htmlescape(node.astext()).replace('"','"')
                     f.write(object_sitemap % (title, link))
                 elif isinstance(node, nodes.bullet_list):
                     if ullevel != 0:
@@ -259,20 +270,20 @@ def istoctree(node):
             def write_index(title, refs, subitems):
                 def write_param(name, value):
                     item = '    <param name="%s" value="%s">\n' % \
-                        (name, value[1])
+                        (name, value)
                     f.write(item)
-                title = cgi.escape(title)
+                title = htmlescape(title)
                 f.write('<LI> <OBJECT type="text/sitemap">\n')
                 write_param('Keyword', title)
                 if len(refs) == 0:
                     write_param('See Also', title)
                 elif len(refs) == 1:
-                    write_param('Local', refs[0])
+                    write_param('Local', refs[0][1])
                 else:
                     for i, ref in enumerate(refs):
                         # XXX: better title?
-                        write_param('Name', '[%d] %s' % (i, ref))
-                        write_param('Local', ref)
+                        write_param('Name', '[%d] %s' % (i, ref[1]))
+                        write_param('Local', ref[1])
                 f.write('</OBJECT>\n')
                 if subitems:
                     f.write('<UL> ')

sphinx/builders/qthelp.py

@@ -14,12 +14,12 @@
 import codecs
 import posixpath
 from os import path
-from cgi import escape
 
 from docutils import nodes
 
 from sphinx import addnodes
 from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.util.pycompat import htmlescape
 
 
 _idpattern = re.compile(
@@ -164,7 +164,7 @@ def build_qhp(self, outdir, outname):
                        fn.endswith('.html'):
                     filename = path.join(root, fn)[olen:]
                     projectfiles.append(file_template %
-                                        {'filename': escape(filename)})
+                                        {'filename': htmlescape(filename)})
         projectfiles = '\n'.join(projectfiles)
 
         # it seems that the "namespace" may not contain non-alphanumeric
@@ -179,12 +179,12 @@ def build_qhp(self, outdir, outname):
         f = codecs.open(path.join(outdir, outname+'.qhp'), 'w', 'utf-8')
         try:
             f.write(project_template % {
-                'outname': escape(outname),
-                'title': escape(self.config.html_title),
-                'version': escape(self.config.version),
-                'project': escape(self.config.project),
-                'namespace': escape(nspace),
-                'masterdoc': escape(self.config.master_doc),
+                'outname': htmlescape(outname),
+                'title': htmlescape(self.config.html_title),
+                'version': htmlescape(self.config.version),
+                'project': htmlescape(self.config.project),
+                'namespace': htmlescape(nspace),
+                'masterdoc': htmlescape(self.config.master_doc),
                 'sections': sections,
                 'keywords': keywords,
                 'files': projectfiles})
@@ -199,10 +199,10 @@ def build_qhp(self, outdir, outname):
         f = codecs.open(path.join(outdir, outname+'.qhcp'), 'w', 'utf-8')
         try:
             f.write(collection_template % {
-                'outname': escape(outname),
-                'title': escape(self.config.html_short_title),
-                'homepage': escape(homepage),
-                'startpage': escape(startpage)})
+                'outname': htmlescape(outname),
+                'title': htmlescape(self.config.html_short_title),
+                'homepage': htmlescape(homepage),
+                'startpage': htmlescape(startpage)})
         finally:
             f.close()
 
@@ -224,7 +224,7 @@ def write_toc(self, node, indentlevel=4):
         if self.isdocnode(node):
             refnode = node.children[0][0]
             link = refnode['refuri']
-            title = escape(refnode.astext()).replace('"','"')
+            title = htmlescape(refnode.astext()).replace('"','"')
             item = '<section title="%(title)s" ref="%(ref)s">' % {
                                                                 'title': title,
                                                                 'ref': link}
@@ -237,7 +237,7 @@ def write_toc(self, node, indentlevel=4):
                 parts.extend(self.write_toc(subnode, indentlevel))
         elif isinstance(node, nodes.reference):
             link = node['refuri']
-            title = escape(node.astext()).replace('"','&quot;')
+            title = htmlescape(node.astext()).replace('"','&quot;')
             item = section_template % {'title': title, 'ref': link}
             item = u' ' * 4 * indentlevel + item
             parts.append(item.encode('ascii', 'xmlcharrefreplace'))
@@ -274,7 +274,7 @@ def keyword_item(self, name, ref):
     def build_keywords(self, title, refs, subitems):
         keywords = []
 
-        title = escape(title)
+        title = htmlescape(title)
 #        if len(refs) == 0: # XXX
 #            write_param('See Also', title)
         if len(refs) == 1:

sphinx/cmdline.py

@@ -22,7 +22,7 @@
 from sphinx.application import Sphinx
 from sphinx.util import Tee, format_exception_cut_frames, save_traceback
 from sphinx.util.console import red, nocolor, color_terminal
-from sphinx.util.pycompat import terminal_safe
+from sphinx.util.pycompat import terminal_safe, bytes
 
 
 def usage(argv, msg=None):
@@ -138,7 +138,7 @@ def main(argv):
             try:
                 val = int(val)
             except ValueError:
-                if likely_encoding:
+                if likely_encoding and isinstance(val, bytes):
                     try:
                         val = val.decode(likely_encoding)
                     except UnicodeError:
@@ -154,7 +154,7 @@ def main(argv):
             try:
                 val = int(val)
             except ValueError:
-                if likely_encoding:
+                if likely_encoding and isinstance(val, bytes):
                     try:
                         val = val.decode(likely_encoding)
                     except UnicodeError:

sphinx/domains/python.py

@@ -525,7 +525,8 @@ def generate(self, docnames=None):
                 # it's a submodule
                 if prev_modname == package:
                     # first submodule - make parent a group head
-                    entries[-1][1] = 1
+                    if entries:
+                        entries[-1][1] = 1
                 elif not prev_modname.startswith(package):
                     # submodule without parent in list, add dummy entry
                     entries.append([stripped + package, 1, '', '', '', '', ''])
@@ -625,22 +626,23 @@ def find_obj(self, env, modname, classname, name, type, searchmode=0):
         newname = None
         if searchmode == 1:
             objtypes = self.objtypes_for_role(type)
-            if modname and classname:
-                fullname = modname + '.' + classname + '.' + name
-                if fullname in objects and objects[fullname][1] in objtypes:
-                    newname = fullname
-            if not newname:
-                if modname and modname + '.' + name in objects and \
-                   objects[modname + '.' + name][1] in objtypes:
-                    newname = modname + '.' + name
-                elif name in objects and objects[name][1] in objtypes:
-                    newname = name
-                else:
-                    # "fuzzy" searching mode
-                    searchname = '.' + name
-                    matches = [(oname, objects[oname]) for oname in objects
-                               if oname.endswith(searchname)
-                               and objects[oname][1] in objtypes]
+            if objtypes is not None:
+                if modname and classname:
+                    fullname = modname + '.' + classname + '.' + name
+                    if fullname in objects and objects[fullname][1] in objtypes:
+                        newname = fullname
+                if not newname:
+                    if modname and modname + '.' + name in objects and \
+                       objects[modname + '.' + name][1] in objtypes:
+                        newname = modname + '.' + name
+                    elif name in objects and objects[name][1] in objtypes:
+                        newname = name
+                    else:
+                        # "fuzzy" searching mode
+                        searchname = '.' + name
+                        matches = [(oname, objects[oname]) for oname in objects
+                                   if oname.endswith(searchname)
+                                   and objects[oname][1] in objtypes]
         else:
             # NOTE: searching for exact match, object type is not considered
             if name in objects:

sphinx/domains/std.py

@@ -245,6 +245,9 @@ def run(self):
                 continue
             # unindented line -> a term
             if line and not line[0].isspace():
+                # enable comments
+                if line.startswith('.. '):
+                    continue
                 # first term of definition
                 if in_definition:
                     if not was_empty:
@@ -315,7 +318,8 @@ def run(self):
             term += system_messages
 
             defnode = nodes.definition()
-            self.state.nested_parse(definition, definition.items[0][1], defnode)
+            if definition:
+                self.state.nested_parse(definition, definition.items[0][1], defnode)
 
             items.append((termtexts,
                           nodes.definition_list_item('', term, defnode)))