[Python-checkins] r62538 - in doctools/trunk: CHANGES doc/conf.py doc/config.rst doc/templating.rst sphinx/builder.py sphinx/config.py sphinx/latexwriter.py sphinx/quickstart.py sphinx/templates/layout.html sphinx/templates/macros.html sphinx/texinputs/howto.cls sphinx/texinputs/manual.cls

Sun Apr 27 21:43:46 CEST 2008

Author: georg.brandl
Date: Sun Apr 27 21:43:45 2008
New Revision: 62538
Log:
Add logo options, add blocks to sidebar.
Removed:
 doctools/trunk/sphinx/templates/macros.html
Modified:
 doctools/trunk/CHANGES
 doctools/trunk/doc/conf.py
 doctools/trunk/doc/config.rst
 doctools/trunk/doc/templating.rst
 doctools/trunk/sphinx/builder.py
 doctools/trunk/sphinx/config.py
 doctools/trunk/sphinx/latexwriter.py
 doctools/trunk/sphinx/quickstart.py
 doctools/trunk/sphinx/templates/layout.html
 doctools/trunk/sphinx/texinputs/howto.cls
 doctools/trunk/sphinx/texinputs/manual.cls
Modified: doctools/trunk/CHANGES
==============================================================================

--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Sun Apr 27 21:43:45 2008
@@ -25,7 +25,8 @@
 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 @@
 - 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 @@
 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.
+
+* 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.
+Thanks to Jacob Kaplan-Moss, Talin, Jeroen Ruigrok van der Werven and Sebastian
+Wiesner for suggestions.
 
 Bugs fixed
 ----------
Modified: doctools/trunk/doc/conf.py
==============================================================================
--- doctools/trunk/doc/conf.py	(original)
+++ doctools/trunk/doc/conf.py	Sun Apr 27 21:43:45 2008
@@ -120,6 +120,8 @@
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
 'Georg Brandl', 'manual')]
 
+latex_logo = '_static/sphinx.png'
+
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
 
Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst	(original)
+++ doctools/trunk/doc/config.rst	Sun Apr 27 21:43:45 2008
@@ -163,6 +163,12 @@
 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 @@
 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.
Modified: doctools/trunk/doc/templating.rst
==============================================================================
--- doctools/trunk/doc/templating.rst	(original)
+++ doctools/trunk/doc/templating.rst	Sun Apr 27 21:43:45 2008
@@ -125,6 +125,20 @@
 (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.
Modified: doctools/trunk/sphinx/builder.py
==============================================================================
--- doctools/trunk/sphinx/builder.py	(original)
+++ doctools/trunk/sphinx/builder.py	Sun Apr 27 21:43:45 2008
@@ -320,20 +320,23 @@
 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 @@
 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 @@
 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):
Modified: doctools/trunk/sphinx/config.py
==============================================================================
--- doctools/trunk/sphinx/config.py	(original)
+++ doctools/trunk/sphinx/config.py	Sun Apr 27 21:43:45 2008
@@ -47,6 +47,7 @@
 # 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 @@
 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),
Modified: doctools/trunk/sphinx/latexwriter.py
==============================================================================
--- doctools/trunk/sphinx/latexwriter.py	(original)
+++ doctools/trunk/sphinx/latexwriter.py	Sun Apr 27 21:43:45 2008
@@ -15,6 +15,7 @@
 import re
 import sys
 import time
+from os import path
 
 from docutils import nodes, writers
 
@@ -30,6 +31,7 @@
 \date{%(date)s}
 \release{%(release)s}
 \author{%(author)s}
+\newcommand{\sphinxlogo}{%(logo)s}
 %(preamble)s
 \makeindex
 '''
@@ -96,6 +98,9 @@
 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 @@
 # 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(
Modified: doctools/trunk/sphinx/quickstart.py
==============================================================================
--- doctools/trunk/sphinx/quickstart.py	(original)
+++ doctools/trunk/sphinx/quickstart.py	Sun Apr 27 21:43:45 2008
@@ -100,6 +100,10 @@
 # "<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 @@
 ('%(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 = ''
 
Modified: doctools/trunk/sphinx/templates/layout.html
==============================================================================
--- doctools/trunk/sphinx/templates/layout.html	(original)
+++ doctools/trunk/sphinx/templates/layout.html	Sun Apr 27 21:43:45 2008
@@ -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" />
Deleted: doctools/trunk/sphinx/templates/macros.html
==============================================================================
--- doctools/trunk/sphinx/templates/macros.html	Sun Apr 27 21:43:45 2008
+++ (empty file)
@@ -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 %}
-
Modified: doctools/trunk/sphinx/texinputs/howto.cls
==============================================================================
--- doctools/trunk/sphinx/texinputs/howto.cls	(original)
+++ doctools/trunk/sphinx/texinputs/howto.cls	Sun Apr 27 21:43:45 2008
@@ -66,6 +66,7 @@
 \endgroup
 \fi
 \begin{flushright}
+ \sphinxlogo%
 {\rm\Huge\py at HeaderFamily \@title} \par
 {\em\large\py at HeaderFamily \py at release\releaseinfo} \par
 \vspace{25pt}
Modified: doctools/trunk/sphinx/texinputs/manual.cls
==============================================================================
--- doctools/trunk/sphinx/texinputs/manual.cls	(original)
+++ doctools/trunk/sphinx/texinputs/manual.cls	Sun Apr 27 21:43:45 2008
@@ -79,6 +79,7 @@
 \endgroup
 \fi
 \begin{flushright}%
+ \sphinxlogo%
 {\rm\Huge\py at HeaderFamily \@title \par}%
 {\em\LARGE\py at HeaderFamily \py at release\releaseinfo \par}
 \vfill
