Add logo options, add blocks to sidebar.

CHANGES

@@ -25,7 +25,8 @@ Incompatible changes
   and putting ``'index': name of your template`` in ``html_additional_pages``.
 
 * In the layout template, redundant ``block``\s were removed; you should use
-  Jinja's standard ``{{ super() }}`` mechanism instead.
+  Jinja's standard ``{{ super() }}`` mechanism instead, as explained in the
+  (newly written) templating docs.
 
 New features added
 ------------------
@@ -53,7 +54,7 @@ New features added
   - Allow giving multiple options in a ``cmdoption`` directive.
   - Fix display of class members without explicit class name given.
 
-* Templates:
+* Templates (HTML output):
 
   - ``index.html`` renamed to ``defindex.html``, see above.
   - There's a new config value, ``html_title``, that controls the overall
@@ -66,9 +67,21 @@ New features added
     HTML output.
   - You can now create an OpenSearch description file with the
     ``html_use_opensearch`` config value.
+  - You can now quickly include a logo in the sidebar, using the ``html_logo``
+    config value.
+  - There are new blocks in the sidebar, so that you can easily insert content
+    into the sidebar.
 
-Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and
+* LaTeX output:
-Sebastian Wiesner for suggestions.
+
+  - The ``sphinx.sty`` package was cleaned of unused stuff.
+  - You can include a logo in the title page with the ``latex_logo`` config
+    value.
+  - You can define the link colors and a border and background color for
+    verbatim environments.
+
+Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and Sebastian
+Wiesner for suggestions.
 
 Bugs fixed
 ----------

doc/conf.py

@@ -120,6 +120,8 @@ htmlhelp_basename = 'Sphinxdoc'
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
                     'Georg Brandl', 'manual')]
 
+latex_logo = '_static/sphinx.png'
+
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
 

doc/config.rst

@@ -163,6 +163,12 @@ that use Sphinx' HTMLWriter class.
    in Sphinx' :file:`static/` path, or in one of the custom paths given in
    :confval:`html_static_path`.  Default is ``'default.css'``.
 
+.. confval:: html_logo
+
+   If given, this must be the name of an image file (within the static path, see
+   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_static_path
 
    A list of paths that contain custom static files (such as style sheets or
@@ -280,6 +286,12 @@ These options influence LaTeX output.
      documents will get appendices.  Also, howtos will have a simpler title
      page.
 
+.. confval:: latex_logo
+
+   If given, this must be the name of an image file (relative to the
+   documentation root) that is the logo of the docs.  It is placed at the top of
+   the title page.  Default: ``None``.
+
 .. confval:: latex_appendices
 
    Documents to append as an appendix to all manuals.

doc/templating.rst

@@ -125,6 +125,20 @@ The following blocks exist in the ``layout`` template:
     (The `sidebar2` location for the sidebar is needed by the ``sphinxdoc.css``
     stylesheet, for example.)
 
+`sidebarlogo`
+    The logo location within the sidebar.  Override this if you want to place
+    some content at the top of the sidebar.
+
+`sidebartoc`
+    The table of contents within the sidebar.
+
+`sidebarrel`
+    The relation links (previous, next document) within the sidebar.
+
+`sidebarsearch`
+    The search box within the sidebar.  Override this if you want to place some
+    content at the bottom of the sidebar.
+
 `footer`
     The block for the footer div.  If you want a custom footer or markup before
     or after it, override this one.

sphinx/builder.py

@@ -320,20 +320,23 @@ class StandaloneHTMLBuilder(Builder):
         docstitle = self.config.html_title or \
                     '%s v%s documentation' % (self.config.project,
                                               self.config.release)
+        logo = self.config.html_logo and \
+               path.basename(self.config.html_logo) or ''
 
         self.globalcontext = dict(
             project = self.config.project,
             release = self.config.release,
             version = self.config.version,
             last_updated = self.last_updated,
-            docstitle = docstitle,
             copyright = self.config.copyright,
             style = self.config.html_style,
             use_modindex = self.config.html_use_modindex,
             use_opensearch = self.config.html_use_opensearch,
+            docstitle = docstitle,
             builder = self.name,
             parents = [],
             titles = {},
+            logo = logo,
             len = len, # the built-in
         )
 
@@ -484,6 +487,12 @@ class StandaloneHTMLBuilder(Builder):
                 self.info(' '+src, nonl=1)
                 shutil.copyfile(path.join(self.srcdir, src),
                                 path.join(self.outdir, '_images', dest))
+            # the logo is handled differently
+            if self.config.html_logo:
+                logobase = path.basename(self.config.html_logo)
+                self.info(' '+logobase, nonl=1)
+                shutil.copyfile(path.join(self.srcdir, self.config.html_logo),
+                                path.join(self.outdir, '_static', logobase))
             self.info()
 
         # copy static files
@@ -806,6 +815,13 @@ class LaTeXBuilder(Builder):
                                 path.join(self.outdir, dest))
             self.info()
 
+        # the logo is handled differently
+        if self.config.latex_logo:
+            logobase = path.basename(self.config.latex_logo)
+            self.info(' '+logobase, nonl=1)
+            shutil.copyfile(path.join(self.srcdir, self.config.latex_logo),
+                            path.join(self.outdir, logobase))
+
         self.info(bold('copying TeX support files...'))
         staticdirname = path.join(path.dirname(__file__), 'texinputs')
         for filename in os.listdir(staticdirname):

sphinx/config.py

@@ -47,6 +47,7 @@ class Config(object):
         # HTML options
         html_title = (None, False),
         html_style = ('default.css', False),
+        html_logo = (None, False),
         html_static_path = ([], False),
         html_last_updated_fmt = ('%b %d, %Y', False),
         html_use_smartypants = (True, False),
@@ -64,6 +65,7 @@ class Config(object):
         latex_paper_size = ('letter', False),
         latex_font_size = ('10pt', False),
         latex_documents = ([], False),
+        latex_logo = (None, False),
         latex_preamble = ('', False),
         latex_appendices = ([], False),
         latex_use_modindex = (True, False),

sphinx/latexwriter.py

@@ -15,6 +15,7 @@
 import re
 import sys
 import time
+from os import path
 
 from docutils import nodes, writers
 
@@ -30,6 +31,7 @@ HEADER = r'''%% Generated by Sphinx.
 \date{%(date)s}
 \release{%(release)s}
 \author{%(author)s}
+\newcommand{\sphinxlogo}{%(logo)s}
 %(preamble)s
 \makeindex
 '''
@@ -96,6 +98,9 @@ class LaTeXTranslator(nodes.NodeVisitor):
         if paper == 'paper': # e.g. command line "-D latex_paper_size="
             paper = 'letterpaper'
         date = time.strftime(builder.config.today_fmt)
+        logo = (builder.config.latex_logo and
+                "\\includegraphics{%s}\\par" % path.basename(builder.config.latex_logo)
+                or '')
         self.options = {'docclass': docclass,
                         'papersize': paper,
                         'pointsize': builder.config.latex_font_size,
@@ -106,6 +111,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
                         # if empty, the title is set to the first section title
                         'title': document.settings.title,
                         'release': builder.config.release,
+                        'logo': logo,
                         'date': date,
                         }
         self.highlighter = highlighting.PygmentsBridge(

sphinx/quickstart.py

@@ -100,6 +100,10 @@ html_style = 'default.css'
 # "<project> v<release> documentation".
 #html_title = None
 
+# The name of an image file (within the static path) to place at the top of
+# the sidebar.
+#html_logo = 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".
@@ -149,6 +153,10 @@ latex_documents = [
   ('%(master)s', '%(project)s.tex', '%(project)s Documentation', '%(author)s', 'manual'),
 ]
 
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
 

sphinx/templates/layout.html

@@ -4,9 +4,7 @@
 {%- endblock %}
 {%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %}
 {%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %}
-{%- include "macros.html" %}
 {%- macro relbar %}
-{# this macro needs to stay in layout.html due to it containing blocks #}
     <div class="related">
       <h3>Navigation</h3>
       <ul>
@@ -34,6 +32,64 @@
       </ul>
     </div>
 {%- endmacro %}
+{%- macro sidebar %}
+      {%- if builder != 'htmlhelp' %}
+      <div class="sidebar">
+        <div class="sidebarwrapper">
+          {%- block sidebarlogo %}
+          {%- if logo %}
+            <p><img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/></p>
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebartoc %}
+          {%- if display_toc %}
+            <h3>Table Of Contents</h3>
+            {{ toc }}
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebarrel %}
+          {%- if prev %}
+            <h4>Previous topic</h4>
+            <p class="topless"><a href="{{ prev.link|e }}" title="previous chapter">{{ prev.title }}</a></p>
+          {%- endif %}
+          {%- if next %}
+            <h4>Next topic</h4>
+            <p class="topless"><a href="{{ next.link|e }}" title="next chapter">{{ next.title }}</a></p>
+          {%- endif %}
+          {%- endblock %}
+          {%- if sourcename %}
+            <h3>This Page</h3>
+            <ul class="this-page-menu">
+            {%- if builder == 'web' %}
+              <li><a href="#comments">Comments ({{ comments|length }} so far)</a></li>
+              <li><a href="{{ pathto('@edit/' + sourcename)|e }}">Suggest Change</a></li>
+              <li><a href="{{ pathto('@source/' + sourcename)|e }}">Show Source</a></li>
+            {%- elif builder == 'html' %}
+              <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}">Show Source</a></li>
+            {%- endif %}
+            </ul>
+          {%- endif %}
+          {%- if customsidebar %}
+          {{ rendertemplate(customsidebar) }}
+          {%- endif %}
+          {%- block sidebarsearch %}
+          {%- if current_page_name != "search" %}
+            <h3>{{ builder == 'web' and 'Keyword' or 'Quick' }} search</h3>
+            <form class="search" action="{{ pathto('search') }}" method="get">
+              <input type="text" name="q" size="18"> <input type="submit" value="Go" />
+              <input type="hidden" name="check_keywords" value="yes" />
+              <input type="hidden" name="area" value="default" />
+            </form>
+            {%- if builder == 'web' %}
+            <p style="font-size: 90%">Enter a module, class or function name.</p>
+            {%- endif %}
+          {%- endif %}
+          {%- endblock %}
+        </div>
+      </div>
+      {%- endif %}
+{%- endmacro -%}
+
 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

sphinx/templates/macros.html

@@ -1,47 +0,0 @@
-{%- macro sidebar %}
-      {%- if builder != 'htmlhelp' %}
-      <div class="sidebar">
-        <div class="sidebarwrapper">
-          {% if display_toc %}
-            <h3>Table Of Contents</h3>
-            {{ toc }}
-          {% endif %}
-          {%- if prev %}
-            <h4>Previous topic</h4>
-            <p class="topless"><a href="{{ prev.link|e }}" title="previous chapter">{{ prev.title }}</a></p>
-          {%- endif %}
-          {%- if next %}
-            <h4>Next topic</h4>
-            <p class="topless"><a href="{{ next.link|e }}" title="next chapter">{{ next.title }}</a></p>
-          {%- endif %}
-          {% if sourcename %}
-            <h3>This Page</h3>
-            <ul class="this-page-menu">
-            {% if builder == 'web' %}
-              <li><a href="#comments">Comments ({{ comments|length }} so far)</a></li>
-              <li><a href="{{ pathto('@edit/' + sourcename)|e }}">Suggest Change</a></li>
-              <li><a href="{{ pathto('@source/' + sourcename)|e }}">Show Source</a></li>
-            {% elif builder == 'html' %}
-              <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}">Show Source</a></li>
-            {% endif %}
-            </ul>
-          {% endif %}
-          {% if customsidebar %}
-          {{ rendertemplate(customsidebar) }}
-          {% endif %}
-          {% if current_page_name != "search" %}
-            <h3>{{ builder == 'web' and 'Keyword' or 'Quick' }} search</h3>
-            <form class="search" action="{{ pathto('search') }}" method="get">
-              <input type="text" name="q" size="18"> <input type="submit" value="Go" />
-              <input type="hidden" name="check_keywords" value="yes" />
-              <input type="hidden" name="area" value="default" />
-            </form>
-            {% if builder == 'web' %}
-            <p style="font-size: 90%">Enter a module, class or function name.</p>
-            {% endif %}
-          {% endif %}
-        </div>
-      </div>
-      {%- endif %}
-{%- endmacro %}
-

sphinx/texinputs/howto.cls

@@ -66,6 +66,7 @@
     \endgroup
   \fi
   \begin{flushright}
+    \sphinxlogo%
     {\rm\Huge\py@HeaderFamily \@title} \par
     {\em\large\py@HeaderFamily \py@release\releaseinfo} \par
     \vspace{25pt}

sphinx/texinputs/manual.cls

@@ -79,6 +79,7 @@
       \endgroup
     \fi
     \begin{flushright}%
+      \sphinxlogo%
       {\rm\Huge\py@HeaderFamily \@title \par}%
       {\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par}
       \vfill