Add logo options, add blocks to sidebar.

2025-02-25 18:55:22 -06:00 · 2008-04-27 19:43:45 +00:00 · 2008-04-27 19:43:45 +00:00 · 262edb1413
commit 262edb1413
parent f7f2cf3a81
12 changed files with 138 additions and 54 deletions
--- a/21
+++ b/21
@ -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
-Sebastian Wiesner for suggestions.
+* LaTeX output:
+
+  - 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
 ----------
--- a/doc/conf.py
+++ b/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 = ''

--- a/doc/config.rst
+++ b/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.
--- a/doc/templating.rst
+++ b/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.
--- a/sphinx/builder.py
+++ b/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):
--- a/sphinx/config.py
+++ b/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),
--- a/sphinx/latexwriter.py
+++ b/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(
--- a/sphinx/quickstart.py
+++ b/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 = ''

--- a/sphinx/templates/layout.html
+++ b/sphinx/templates/layout.html
@ -4,9 +4,7 @@
 {%- endblock %}
 {%- set reldelim1 = reldelim1 is not defined and ' &raquo;' 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" />
--- a/sphinx/templates/macros.html
+++ b/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 %}
-
--- a/sphinx/texinputs/howto.cls
+++ b/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}
--- a/sphinx/texinputs/manual.cls
+++ b/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