Georg Brandl avatar Georg Brandl committed fc3e0f4

Review changes from and add docs.

Comments (0)

Files changed (8)

 * 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
 * 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
    .. 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'``.


   '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/
-        #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
   'pickling environment... '), nonl=True)


         self.docsettings = OptionParser(
+        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
         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'),
         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),


     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.
+        Specifically implemented for 'Indices and Tables' section, which looks
+        odd when html_compact_lists is false.
         if self.config.html_compact_lists:
         class RefOnlyListChecker(nodes.GenericNodeVisitor):
-            """Raise `nodes.NodeFound` if non-simple list item is
-            encountered.
+            """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.
+            Here 'simple' means a list item containing only a paragraph with a
+            single reference in it.
+            """
-            """
             def default_visit(self, node):
                 raise nodes.NodeFound
             except nodes.NodeFound:
-                return None
+                return False
-                return 1
+                return True
         for node in doctree.traverse(nodes.bullet_list):
             if check_refonly_list(node):


         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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.