From 66b5f39bc7e07fe5a6cd16784d7f7bec0aa152ad Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 15 Jun 2008 08:48:06 +0000 Subject: [PATCH] Add html_favicon config value. --- CHANGES | 65 +++++++++++++++++++++--------------- doc/config.rst | 9 +++++ sphinx/builder.py | 6 ++++ sphinx/config.py | 1 + sphinx/directives/desc.py | 3 ++ sphinx/quickstart.py | 5 +++ sphinx/templates/layout.html | 7 ++-- 7 files changed, 67 insertions(+), 29 deletions(-) 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') %}