Add html_favicon config value.

CHANGES

@@ -4,42 +4,53 @@ Changes in trunk
 New features added
 ------------------
 
-* A new config value, `html_file_suffix`, can be used to set the HTML file
+* ``tocdepth`` can be given as a file-wide metadata entry, and
-  suffix to e.g. ``.xhtml``.
+  specifies the maximum depth of a TOC of this file.
 
-* The `autodoc` extension accepts signatures for functions, methods and
+* HTML output:
-  classes now that override the signature got via introspection from
-  Python code.
 
-* The new config value `html_use_index` can be used to switch index
+  - The "previous" and "next" links have a more logical structure, so
-  generation in HTML documents off.
+    that by following "next" links you can traverse the entire TOC
+    tree.
 
-* The new `exclude_trees` config option can be used to exclude whole
+  - The new event `html-page-context` can be used to include custom
+    values into the context used when rendering an HTML template.
+
+  - Document metadata is now in the default template context, under
+    the name `metadata`.
+
+  - The new config value `html_favicon` can be used to set a favicon
+    for the HTML output.  Thanks to Sebastian Wiesner.
+
+  - The new config value `html_use_index` can be used to switch index
+    generation in HTML documents off.
+
+  - The new config value `html_short_title` can be used to set a
+    shorter title for the documentation which is then used in the
+    navigation bar.
+
+  - The new config value `html_show_sphinx` can be used to control
+    whether a link to Sphinx is added to the HTML footer.
+
+  - The new config value `html_file_suffix` can be used to set the
+    HTML file suffix to e.g. ``.xhtml``.
+
+  - The directories in the `html_static_path` can now contain
+    subdirectories.
+
+* The new config value `exclude_trees` can be used to exclude whole
   subtrees from the search for source files.
 
-* The directories in the `html_static_path` can now contain subdirectories.
-
-* The new config value `html_short_title` can be used to set a shorter
-  title for the documentation which is then used in the navigation bar.
-
-* The new config value `html_show_sphinx` can be used to control whether
-  a link to Sphinx is added to the HTML footer.
-
 * Defaults for configuration values can now be callables, which allows
   dynamic defaults.
 
-* The new ``html-page-context`` event can be used to include custom values
+* The new TextBuilder creates plain-text output.
-  into the context used when rendering an HTML template.
 
-* Add document metadata to the values in the default template context.
+* Extensions:
-
+    
-* Let the "previous" and "next" to more logical documents, so that by
+  - The `autodoc` extension accepts signatures for functions, methods
-  following "next" links you can traverse the entire TOC tree.
+    and classes now that override the signature got via introspection
-
+    from Python code.
-* Added TextBuilder to create plain-text output.
-
-* ``tocdepth`` can be given as a file-wide metadata entry, and specifies
-  the maximum depth of a TOC of this file.
 
 Bugs fixed
 ----------

doc/config.rst

@@ -202,6 +202,15 @@ that use Sphinx' HTMLWriter class.
    below) that is the logo of the docs.  It is placed at the top of the sidebar;
    its width should therefore not exceed 200 pixels.  Default: ``None``.
 
+.. confval:: html_favicon
+
+   If given, this must be the name of an image file (within the static path, see
+   below) that is the favicon of the docs.  Modern browsers use this as icon for
+   tabs, windows and bookmarks.  It should be a Windows-style icon file
+   (``.ico``), which is 16x16 or 32x32 pixels large.  Default: ``None``.
+
+   .. versionadded:: 0.4
+
 .. confval:: html_static_path
 
    A list of paths that contain custom static files (such as style sheets or

sphinx/builder.py

@@ -321,6 +321,11 @@ class StandaloneHTMLBuilder(Builder):
         logo = self.config.html_logo and \
                path.basename(self.config.html_logo) or ''
 
+        favicon = self.config.html_favicon and \
+                  path.basename(self.config.html_favicon) or ''
+        if os.path.splitext(favicon)[1] != '.ico':
+            self.warn('html_favicon is not an .ico file')
+
         if not isinstance(self.config.html_use_opensearch, basestring):
             self.warn('html_use_opensearch config value must now be a string')
 
@@ -342,6 +347,7 @@ class StandaloneHTMLBuilder(Builder):
             builder = self.name,
             parents = [],
             logo = logo,
+            favicon = favicon,
             len = len, # the built-in
         )
 

sphinx/config.py

@@ -50,6 +50,7 @@ class Config(object):
         html_short_title = (lambda self: self.html_title, False),
         html_style = ('default.css', False),
         html_logo = (None, False),
+        html_favicon = (None, False),
         html_static_path = ([], False),
         html_last_updated_fmt = ('%b %d, %Y', False),
         html_use_smartypants = (True, False),

sphinx/directives/desc.py

@@ -445,3 +445,6 @@ def target_directive(targettype, arguments, options, content, lineno,
 
 target_directive.content = 0
 target_directive.arguments = (1, 0, 1)
+
+# note, the target directive is not registered here, it is used by the application
+# when registering additional xref types

sphinx/quickstart.py

@@ -112,6 +112,11 @@ html_style = 'default.css'
 # the sidebar.
 #html_logo = None
 
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

sphinx/templates/layout.html

@@ -119,12 +119,15 @@
     <script type="text/javascript" src="{{ pathto('_static/jquery.js', 1) }}"></script>
     <script type="text/javascript" src="{{ pathto('_static/interface.js', 1) }}"></script>
     <script type="text/javascript" src="{{ pathto('_static/doctools.js', 1) }}"></script>
-    {%- endif %}
+    {%- if use_opensearch %}
-    {%- if use_opensearch and builder != 'htmlhelp' %}
     <link rel="search" type="application/opensearchdescription+xml"
           title="Search within {{ docstitle }}"
           href="{{ pathto('_static/opensearch.xml', 1) }}"/>
     {%- endif %}
+    {%- if favicon %}
+    <link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
+    {%- endif %}
+    {%- endif %}
 {%- block rellinks %}
     {%- if hasdoc('about') %}
     <link rel="author" title="About these documents" href="{{ pathto('about') }}" />