merge with http://bitbucket.org/tpowers/sphinx/

.hgignore

@@ -11,3 +11,4 @@ TAGS
 \.ropeproject/
 ^env/
 \.DS_Store$
+~$

sphinx/builders/__init__.py

@@ -300,6 +300,19 @@ class Builder(object):
         else:
             self.info('none found')
 
+        #%%%%% Don't know where else to put this???  Change
+        #env.settings since that seems to be the only way to change
+        #the StandaloneHTMLBuilder(Builder)'s docsettings.  These
+        #docsettings are stored in doctree.settings, which eventually
+        #get passed to HTMLWriter, which actually creates
+        #docutils/writers/html4css1/__init__.py/HTMLTranslator(nodes.NodeVisitor).
+        #It's here that these settings are then used to configure the
+        #actual HTML output.
+        if self.config.html_compact_lists:
+            self.env.settings['compact_lists'] = 1
+        else:
+            self.env.settings['compact_lists'] = 0
+
         if updated_docnames:
             # save the environment
             self.info(bold('pickling environment... '), nonl=True)

sphinx/config.py

@@ -59,8 +59,10 @@ class Config(object):
         keep_warnings = (False, 'env'),
         modindex_common_prefix = ([], 'html'),
         rst_epilog = (None, 'env'),
+        rst_prologue = (None, 'env'),
         trim_doctest_flags = (True, 'env'),
         needs_sphinx = (None, None),
+        secnumber_suffix = ('. ', 'html'),
         
         # HTML options
         html_theme = ('default', 'html'),
@@ -93,6 +95,7 @@ class Config(object):
         html_show_sphinx = (True, 'html'),
         html_context = ({}, 'html'),
         html_output_encoding = ('utf-8', 'html'),
+        html_compact_lists = (True, 'html'),
 
         # HTML help only options
         htmlhelp_basename = (lambda self: make_filename(self.project), None),

sphinx/environment.py

@@ -589,9 +589,10 @@ class BuildEnvironment:
                     app.emit('source-read', docname, arg)
                     data = arg[0]
                 if self.config.rst_epilog:
-                    return data + '\n' + self.config.rst_epilog + '\n'
+                    data = data + '\n' + self.config.rst_epilog + '\n'
-                else:
+                if self.config.rst_prologue:
-                    return data
+                    data = self.config.rst_prologue + '\n' + data
+                return data
 
         # publish manually
         pub = Publisher(reader=SphinxStandaloneReader(),
@@ -612,6 +613,7 @@ class BuildEnvironment:
         self.process_images(docname, doctree)
         self.process_downloads(docname, doctree)
         self.process_metadata(docname, doctree)
+        self.process_refonly_bullet_lists(docname, doctree)
         self.create_title_from(docname, doctree)
         self.note_labels_from(docname, doctree)
         self.note_indexentries_from(docname, doctree)
@@ -781,6 +783,69 @@ class BuildEnvironment:
                 md[name.astext()] = body.astext()
         del doctree[0]
 
+    def process_refonly_bullet_lists(self, docname, doctree):
+        """Change refonly bullet lists to use compact_paragraphs.
+
+        Specifically implemented for 'Indices and Tables' section, which
+        looks odd in --no-compact-lists mode.
+
+        """
+        if self.config.html_compact_lists:
+            return
+
+        class RefOnlyListChecker(nodes.GenericNodeVisitor):
+            """Raise `nodes.NodeFound` if non-simple list item is
+            encountered.
+
+            Here 'simple' means a list item containing only a paragraph
+            with a single reference in it.
+
+            """
+            def default_visit(self, node):
+                raise nodes.NodeFound
+
+            def visit_bullet_list(self, node):
+                pass
+
+            def visit_list_item(self, node):
+                children = []
+                for child in node.children:
+                    if not isinstance(child, nodes.Invisible):
+                        children.append(child)
+                if len(children) != 1:
+                    raise nodes.NodeFound
+                if not isinstance(children[0], nodes.paragraph):
+                    raise nodes.NodeFound
+                para = children[0]
+                if len(para) != 1:
+                    raise nodes.NodeFound
+                if not isinstance(para[0], addnodes.pending_xref):
+                    raise nodes.NodeFound
+                raise nodes.SkipChildren
+
+            def invisible_visit(self, node):
+                """Invisible nodes should be ignored."""
+                pass
+
+        def check_refonly_list(node):
+            """Check for list with only references in it."""
+            visitor = RefOnlyListChecker(doctree)
+            try:
+                node.walk(visitor)
+            except nodes.NodeFound:
+                return None
+            else:
+                return 1
+
+        for node in doctree.traverse(nodes.bullet_list):
+            if check_refonly_list(node):
+                for item in node.traverse(nodes.list_item):
+                    para = item[0]
+                    ref = para[0]
+                    compact_para = addnodes.compact_paragraph()
+                    compact_para += ref
+                    item.replace(para, compact_para)
+
     def create_title_from(self, docname, document):
         """
         Add a title node to the document (just copy the first section title),

sphinx/writers/html.py

@@ -59,6 +59,7 @@ class HTMLTranslator(BaseTranslator):
         self.highlightlinenothreshold = sys.maxint
         self.protect_literal_text = 0
         self.add_permalinks = builder.config.html_add_permalinks
+        self.secnumber_suffix = builder.config.secnumber_suffix
 
     def visit_start_of_file(self, node):
         # only occurs in the single-file builder
@@ -165,7 +166,8 @@ class HTMLTranslator(BaseTranslator):
             self.body[-1] = '<a title="%s"' % self.attval(node['reftitle']) + \
                             starttag[2:]
         if node.hasattr('secnumber'):
-            self.body.append('%s. ' % '.'.join(map(str, node['secnumber'])))
+            self.body.append(('%s' + self.secnumber_suffix) %
+                             '.'.join(map(str, node['secnumber'])))
 
     # overwritten -- we don't want source comments to show up in the HTML
     def visit_comment(self, node):
@@ -186,14 +188,16 @@ class HTMLTranslator(BaseTranslator):
 
     def add_secnumber(self, node):
         if node.hasattr('secnumber'):
-            self.body.append('.'.join(map(str, node['secnumber'])) + '. ')
+            self.body.append('.'.join(map(str, node['secnumber'])) +
+                             self.secnumber_suffix)
         elif isinstance(node.parent, nodes.section):
             anchorname = '#' + node.parent['ids'][0]
             if anchorname not in self.builder.secnumbers:
                 anchorname = ''  # try first heading which has no anchor
             if anchorname in self.builder.secnumbers:
                 numbers = self.builder.secnumbers[anchorname]
-                self.body.append('.'.join(map(str, numbers)) + '. ')
+                self.body.append('.'.join(map(str, numbers)) +
+                                 self.secnumber_suffix)
 
     # overwritten for docutils 0.4
     if hasattr(BaseTranslator, 'start_tag_with_title'):