1. Georg Brandl
  2. sphinx

Commits

tpowers  committed 462aeee

Implemented html_compact_lists conf.py option. Normally True. When False,
"simple" item lists are not compacted. See
http://docutils.sourceforge.net/FAQ.html#how-are-lists-formatted-in-html.

Bullet lists like the "Indices and Tables" section look odd when they are
not compacted. Therefore specially change any bullet list that only has
paragraph's with pending_xrefs to use compact paragraphs instead.

Implemented secnumber_suffix conf.py option. Default is '. '. Section
numbers look better if changed to u'\u00a0\u00a0'.

  • Participants
  • Parent commits dd46f48
  • Branches default

Comments (0)

Files changed (5)

File .hgignore

View file
 \.ropeproject/
 ^env/
 \.DS_Store$
+~$

File sphinx/builders/__init__.py

View file
         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)

File sphinx/config.py

View file
         rst_epilog = (None, 'env'),
         trim_doctest_flags = (True, 'env'),
         needs_sphinx = (None, None),
-
+        secnumber_suffix = ('. ', 'html'),
+        
         # HTML options
         html_theme = ('default', 'html'),
         html_theme_path = ([], 'html'),
         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),

File sphinx/environment.py

View file
         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)
                 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),

File sphinx/writers/html.py

View file
         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
             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):
 
     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'):