Merge branch 'stable'

CHANGES

@@ -142,7 +142,7 @@ Deprecated
   ``False``.
 * #3221: epub2 builder is deprecated
 
-Release 1.5.4 (in development)
+Release 1.5.5 (in development)
 ==============================
 
 Incompatible changes
@@ -154,8 +154,19 @@ Deprecated
 Features added
 --------------
 
+Bugs fixed
+----------
+
+Testing
+--------
+
+Release 1.5.4 (released Apr 02, 2017)
+=====================================
+
+Features added
+--------------
+
 * #3470: Make genindex support all kinds of letters, not only Latin ones
-* latex macros for directional double quotes (refs #3527)
 
 Bugs fixed
 ----------
@@ -182,9 +193,6 @@ Bugs fixed
 * A LaTeX command such as ``\\large`` inserted in the title items of
   :confval:`latex_documents` causes failed PDF build (refs #3551, #3567)
 
-Testing
---------
-
 Release 1.5.3 (released Feb 26, 2017)
 =====================================
 

doc/ext/autosummary.rst

@@ -158,7 +158,7 @@ is not supported.)
    may indicate that it's a better idea to write custom narrative documentation
    instead.
 
-Autosummary uses the following template files:
+Autosummary uses the following Jinja template files:
 
 - :file:`autosummary/base.rst` -- fallback template
 - :file:`autosummary/module.rst` -- template for modules
@@ -194,7 +194,8 @@ The following variables available in the templates:
 
 .. data:: underline
 
-   A string containing ``len(full_name) * '='``.
+   A string containing ``len(full_name) * '='``. Use the ``underline`` filter
+   instead.
 
 .. data:: members
 
@@ -227,7 +228,25 @@ The following variables available in the templates:
    List containing names of "public" attributes in the class.  Only available
    for classes.
 
+
+Additionally, the following filters are available
+
+.. function:: escape(s)
+
+   Escape any special characters in the text to be used in formatting RST
+   contexts. For instance, this prevents asterisks making things bolt. This
+   replaces the builtin Jinja `escape filter`_ that does html-escaping.
+
+.. function:: underline(s, line='=')
+
+   Add a title underline to a piece of text.
+
+For instance, ``{{ fullname | escape | underline }}`` should be used to produce
+the title of a page.
+
 .. note::
 
    You can use the :rst:dir:`autosummary` directive in the stub pages.
    Stub pages are generated also based on these directives.
+
+.. _`escape filter`: http://jinja.pocoo.org/docs/2.9/templates/#escape

setup.cfg

@@ -3,7 +3,7 @@ tag_build = .dev
 tag_date = true
 
 [aliases]
-release = egg_info -RDb ''
+release = egg_info -Db ''
 upload = upload --sign --identity=36580288
 
 [extract_messages]

sphinx/builders/html.py

@@ -1021,6 +1021,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
         if 'includehidden' not in kwds:
             kwds['includehidden'] = False
         toctree = TocTree(self.env).get_toctree_for(docname, self, collapse, **kwds)
+        if toctree is not None:
             self.fix_refuris(toctree)
         return self.render_partial(toctree)['fragment']
 

sphinx/ext/autosummary/generate.py

@@ -34,6 +34,7 @@ from sphinx.ext.autosummary import import_by_name, get_documenter
 from sphinx.jinja2glue import BuiltinTemplateLoader
 from sphinx.util.osutil import ensuredir
 from sphinx.util.inspect import safe_getattr
+from sphinx.util.rst import escape as rst_escape
 
 # Add documenters to AutoDirective registry
 from sphinx.ext.autodoc import add_documenter, \
@@ -95,6 +96,12 @@ def _simple_warn(msg):
     print('WARNING: ' + msg, file=sys.stderr)
 
 
+def _underline(title, line='='):
+    if '\n' in title:
+        raise ValueError('Can only underline single lines')
+    return title + '\n' + line * len(title)
+
+
 # -- Generating output ---------------------------------------------------------
 
 def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
@@ -130,6 +137,11 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
             template_dirs.insert(0, template_dir)
         template_loader = FileSystemLoader(template_dirs)  # type: ignore
     template_env = SandboxedEnvironment(loader=template_loader)
+    template_env.filters['underline'] = _underline
+
+    # replace the builtin html filters
+    template_env.filters['escape'] = rst_escape
+    template_env.filters['e'] = rst_escape
 
     # read
     items = find_autosummary_in_files(sources)

sphinx/ext/autosummary/templates/autosummary/base.rst

@@ -1,5 +1,4 @@
-{{ fullname }}
+{{ fullname | escape | underline}}
-{{ underline }}
 
 .. currentmodule:: {{ module }}
 

sphinx/ext/autosummary/templates/autosummary/class.rst

@@ -1,5 +1,4 @@
-{{ fullname }}
+{{ fullname | escape | underline}}
-{{ underline }}
 
 .. currentmodule:: {{ module }}
 

sphinx/ext/autosummary/templates/autosummary/module.rst

@@ -1,5 +1,4 @@
-{{ fullname }}
+{{ fullname | escape | underline}}
-{{ underline }}
 
 .. automodule:: {{ fullname }}
 

tests/roots/test-autosummary/contents.rst

@@ -4,4 +4,5 @@
    :toctree:
 
    dummy_module
+   underscore_module_
    sphinx

tests/roots/test-autosummary/underscore_module_.py

@@ -0,0 +1,12 @@
+"""
+module with trailing underscores everywhere
+"""
+class class_(object):
+    """ Class """
+    def method_(_arg):
+        """ Method """
+        pass
+
+def function_(_arg):
+    """ Function """
+    pass

tests/roots/test-toctree-empty/_templates/localtoc.html

@@ -0,0 +1,2 @@
+{# This will call toctree unconditionally, whether there is a local or global toc #}
+{{ toctree() }}

tests/roots/test-toctree-empty/conf.py

@@ -0,0 +1,6 @@
+# -*- coding: utf-8 -*-
+
+master_doc = 'index'
+html_theme = 'classic'
+exclude_patterns = ['_build']
+templates_path = ['_templates']

tests/roots/test-toctree-empty/index.rst

@@ -0,0 +1,4 @@
+test-toctree-empty
+==================
+
+.. toctree::

tests/test_ext_autosummary.py

@@ -13,6 +13,8 @@ from six import iteritems, StringIO
 
 from sphinx.ext.autosummary import mangle_signature
 
+from util import etree_parse
+
 import pytest
 
 html_warnfile = StringIO()
@@ -103,3 +105,24 @@ def test_get_items_summary(app, status, warning):
                   'Test function take an argument ended with underscore.',
                   'dummy_module.func')
     assert autosummary_items['func'] == func_attrs
+
+def str_content(elem):
+    if elem.text is not None:
+        return elem.text
+    else:
+        return ''.join(str_content(e) for e in elem)
+
+@pytest.mark.sphinx('xml', **default_kw)
+def test_escaping(app, status, warning):
+    from xml.etree import ElementTree
+
+    app.builder.build_all()
+
+    outdir = app.builder.outdir
+
+    docpage = outdir / 'underscore_module_.xml'
+    assert docpage.exists()
+
+    title = etree_parse(docpage).find('section/title')
+
+    assert str_content(title) == 'underscore_module_'

tests/test_toctree.py

@@ -26,3 +26,12 @@ def test_relations(app, status, warning):
     assert app.builder.relations['qux/qux_1'] == ['qux/index', 'qux/index', 'qux/qux_2']
     assert app.builder.relations['qux/qux_2'] == ['qux/index', 'qux/qux_1', None]
     assert 'quux' not in app.builder.relations
+
+
+@pytest.mark.sphinx('singlehtml', testroot='toctree-empty')
+def test_singlehtml_toctree(app, status, warning):
+    app.builder.build_all()
+    try:
+        app.builder._get_local_toctree('index')
+    except AttributeError:
+        pytest.fail('Unexpected AttributeError in app.builder.fix_refuris')