diff --git a/CHANGES b/CHANGES
index ddc220088..af43d2d73 100644
--- a/CHANGES
+++ b/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
- suffix to e.g. ``.xhtml``.
+* ``tocdepth`` can be given as a file-wide metadata entry, and
+ specifies the maximum depth of a TOC of this file.
-* The `autodoc` extension accepts signatures for functions, methods and
- classes now that override the signature got via introspection from
- Python code.
+* HTML output:
-* The new config value `html_use_index` can be used to switch index
- generation in HTML documents off.
+ - The "previous" and "next" links have a more logical structure, so
+ 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
- into the context used when rendering an HTML template.
+* The new TextBuilder creates plain-text output.
-* Add document metadata to the values in the default template context.
-
-* Let the "previous" and "next" to more logical documents, so that by
- following "next" links you can traverse the entire TOC tree.
-
-* 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.
+* Extensions:
+
+ - The `autodoc` extension accepts signatures for functions, methods
+ and classes now that override the signature got via introspection
+ from Python code.
Bugs fixed
----------
diff --git a/doc/config.rst b/doc/config.rst
index 838a013e5..c7e257804 100644
--- a/doc/config.rst
+++ b/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
diff --git a/sphinx/builder.py b/sphinx/builder.py
index a8f8edd7d..333321ebe 100644
--- a/sphinx/builder.py
+++ b/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
)
diff --git a/sphinx/config.py b/sphinx/config.py
index b23915dcb..fb5a47e80 100644
--- a/sphinx/config.py
+++ b/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),
diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py
index 310a7bf3e..ca9853e95 100644
--- a/sphinx/directives/desc.py
+++ b/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
diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py
index 55869285a..17cb9f599 100644
--- a/sphinx/quickstart.py
+++ b/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".
diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html
index 749209fb3..df55b0ef6 100644
--- a/sphinx/templates/layout.html
+++ b/sphinx/templates/layout.html
@@ -119,12 +119,15 @@
- {%- endif %}
- {%- if use_opensearch and builder != 'htmlhelp' %}
+ {%- if use_opensearch %}
{%- endif %}
+ {%- if favicon %}
+
+ {%- endif %}
+ {%- endif %}
{%- block rellinks %}
{%- if hasdoc('about') %}