Review changes from http://bitbucket.org/tpowers/sphinx/ and add docs.

AUTHORS

@@ -21,6 +21,7 @@ Other contributors, listed alphabetically, are:
 * Roland Meister -- epub builder
 * Christopher Perkins -- autosummary integration
 * Benjamin Peterson -- unittests
+* T. Powers -- HTML output improvements
 * Stefan Seefeld -- toctree improvements
 * Antonio Valentino -- qthelp builder
 * Pauli Virtanen -- autodoc improvements, autosummary extension

CHANGES

@@ -15,6 +15,12 @@ Release 1.0 (in development)
 
 * Added ``tab-width`` option to ``literalinclude`` directive.
 
+* Added ``html_secnumber_suffix`` config value to control section
+  numbering format.
+
+* Added ``html_compact_lists`` config value to control docutils'
+  compact lists feature.
+
 * The ``html_sidebars`` config value can now contain patterns as
   keys, and the values can be lists that explicitly select which
   sidebar templates should be rendered.  That means that the builtin

doc/config.rst

@@ -614,6 +614,21 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 1.0
 
+.. confval:: html_compact_lists
+
+   If true, list items containing only a single paragraph will not be rendered
+   with a ``<p>`` element.  This is standard docutils behavior.  Default:
+   ``True``.
+
+   .. versionadded:: 1.0
+
+.. confval:: html_secnumber_suffix
+
+   Suffix for section numbers.  Default: ``". "``.  Set to ``" "`` to suppress
+   the final dot on section numbers.
+
+   .. versionadded:: 1.0
+
 .. confval:: htmlhelp_basename
 
    Output file base name for HTML help builder.  Default is ``'pydoc'``.

sphinx/builders/__init__.py

@@ -300,19 +300,6 @@ 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/builders/html.py

@@ -228,6 +228,7 @@ class StandaloneHTMLBuilder(Builder):
         self.docsettings = OptionParser(
             defaults=self.env.settings,
             components=(self.docwriter,)).get_default_values()
+        self.docsettings.compact_lists = bool(self.config.html_compact_lists)
 
         # format the "last updated on" string, only once is enough since it
         # typically doesn't include the time of day

sphinx/config.py

@@ -62,8 +62,7 @@ class Config(object):
         rst_prologue = (None, 'env'),
         trim_doctest_flags = (True, 'env'),
         needs_sphinx = (None, None),
-        secnumber_suffix = ('. ', 'html'),
+
-        
         # HTML options
         html_theme = ('default', 'html'),
         html_theme_path = ([], 'html'),
@@ -96,6 +95,7 @@ class Config(object):
         html_context = ({}, 'html'),
         html_output_encoding = ('utf-8', 'html'),
         html_compact_lists = (True, 'html'),
+        html_secnumber_suffix = ('. ', 'html'),
 
         # HTML help only options
         htmlhelp_basename = (lambda self: make_filename(self.project), None),

sphinx/environment.py

@@ -786,21 +786,19 @@ class BuildEnvironment:
     def process_refonly_bullet_lists(self, docname, doctree):
         """Change refonly bullet lists to use compact_paragraphs.
 
-        Specifically implemented for 'Indices and Tables' section, which
+        Specifically implemented for 'Indices and Tables' section, which looks
-        looks odd in --no-compact-lists mode.
+        odd when html_compact_lists is false.
-
         """
         if self.config.html_compact_lists:
             return
 
         class RefOnlyListChecker(nodes.GenericNodeVisitor):
-            """Raise `nodes.NodeFound` if non-simple list item is
+            """Raise `nodes.NodeFound` if non-simple list item is encountered.
-            encountered.
-
-            Here 'simple' means a list item containing only a paragraph
-            with a single reference in it.
 
+            Here 'simple' means a list item containing only a paragraph with a
+            single reference in it.
             """
+
             def default_visit(self, node):
                 raise nodes.NodeFound
 
@@ -833,9 +831,9 @@ class BuildEnvironment:
             try:
                 node.walk(visitor)
             except nodes.NodeFound:
-                return None
+                return False
             else:
-                return 1
+                return True
 
         for node in doctree.traverse(nodes.bullet_list):
             if check_refonly_list(node):

sphinx/writers/html.py

@@ -59,7 +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
+        self.secnumber_suffix = builder.config.html_secnumber_suffix
 
     def visit_start_of_file(self, node):
         # only occurs in the single-file builder