Add html_add_permalinks config value.

CHANGES

@@ -4,14 +4,21 @@ Release 0.6 (in development)
 New features added
 ------------------
 
+* Configuration:
+
+  - The new ``html_add_permalinks`` config value can be used to
+    switch off the generated "paragraph sign" permalinks for each
+    heading and definition environment.
+
 * Extension API:
 
-  - Add Sphinx.add_lexer() to add custom Pygments lexers.
+  - There is now a Sphinx.add_lexer() method to add custom Pygments
+    lexers.
 
 * Other changes:
 
-  - Allow giving config overrides for single dict keys on the command
-    line.
+  - Config overrides for single dict keys can now be given on the
+    command line.
 
 
 Release 0.5 (Nov 23, 2008) -- Birthday release!

doc/config.rst

@@ -332,6 +332,15 @@ that use Sphinx' HTMLWriter class.
    If true, *SmartyPants* will be used to convert quotes and dashes to
    typographically correct entities.  Default: ``True``.
 
+.. confval:: html_add_permalinks
+
+   If true, Sphinx will add "permalinks" for each heading and description
+   environment as paragraph signs that become visible when the mouse hovers over
+   them.  Default: ``True``.
+
+   .. versionadded:: 0.6
+      Previously, this was always activated.
+   
 .. confval:: html_sidebars
 
    Custom sidebar templates, must be a dictionary that maps document names to

sphinx/builders/html.py

@@ -53,8 +53,7 @@ class StandaloneHTMLBuilder(Builder):
     supported_image_types = ['image/svg+xml', 'image/png', 'image/gif',
                              'image/jpeg']
     searchindex_filename = 'searchindex.js'
-    add_header_links = True
-    add_definition_links = True
+    add_permalinks = True
 
     # This is a class attribute because it is mutated by Sphinx.add_javascript.
     script_files = ['_static/jquery.js', '_static/doctools.js']

sphinx/builders/htmlhelp.py

@@ -132,8 +132,7 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder):
     supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
 
     # don't add links
-    add_header_links = False
-    add_definition_links = False
+    add_permalinks = False
 
     def init(self):
         StandaloneHTMLBuilder.init(self)

sphinx/config.py

@@ -65,6 +65,7 @@ class Config(object):
         html_sidebars = ({}, False),
         html_additional_pages = ({}, False),
         html_use_modindex = (True, False),
+        html_add_permalinks = (True, False),
         html_use_index = (True, False),
         html_split_index = (False, False),
         html_copy_source = (True, False),

sphinx/writers/html.py

@@ -58,6 +58,7 @@ class HTMLTranslator(BaseTranslator):
         self.highlightlang = builder.config.highlight_language
         self.highlightlinenothreshold = sys.maxint
         self.protect_literal_text = 0
+        self.add_permalinks = builder.config.html_add_permalinks
 
     def visit_desc(self, node):
         self.body.append(self.starttag(node, 'dl', CLASS=node['desctype']))
@@ -73,7 +74,7 @@ class HTMLTranslator(BaseTranslator):
         if node.parent['desctype'] in ('class', 'exception'):
             self.body.append('%s ' % node.parent['desctype'])
     def depart_desc_signature(self, node):
-        if node['ids'] and self.builder.add_definition_links:
+        if node['ids'] and self.add_permalinks and self.builder.add_permalinks:
             self.body.append(u'<a class="headerlink" href="#%s" ' % node['ids'][0] +
                              u'title="%s">\u00B6</a>' %
                              _('Permalink to this definition'))
@@ -388,7 +389,7 @@ class HTMLTranslator(BaseTranslator):
 
     def depart_title(self, node):
         close_tag = self.context[-1]
-        if self.builder.add_header_links and \
+        if self.add_permalinks and self.builder.add_permalinks and \
                (close_tag.startswith('</h') or
                 close_tag.startswith('</a></h')) and \
                node.parent.hasattr('ids') and node.parent['ids']: