diff options
author | georg.brandl <devnull@localhost> | 2008-04-27 19:43:45 +0000 |
---|---|---|
committer | georg.brandl <devnull@localhost> | 2008-04-27 19:43:45 +0000 |
commit | 2261b8cdb910257261b5a13da3b1b7bb4bee87ab (patch) | |
tree | 9cacb37c5145a8969ea7a04a8c146a89e5fb2132 | |
parent | 53177297ef3e8699afc6d9c0799f7582b63308d5 (diff) | |
download | sphinx-2261b8cdb910257261b5a13da3b1b7bb4bee87ab.tar.gz |
Add logo options, add blocks to sidebar.
-rw-r--r-- | CHANGES | 21 | ||||
-rw-r--r-- | doc/conf.py | 2 | ||||
-rw-r--r-- | doc/config.rst | 12 | ||||
-rw-r--r-- | doc/templating.rst | 14 | ||||
-rw-r--r-- | sphinx/builder.py | 18 | ||||
-rw-r--r-- | sphinx/config.py | 2 | ||||
-rw-r--r-- | sphinx/latexwriter.py | 6 | ||||
-rw-r--r-- | sphinx/quickstart.py | 8 | ||||
-rw-r--r-- | sphinx/templates/layout.html | 60 | ||||
-rw-r--r-- | sphinx/templates/macros.html | 47 | ||||
-rw-r--r-- | sphinx/texinputs/howto.cls | 1 | ||||
-rw-r--r-- | sphinx/texinputs/manual.cls | 1 |
12 files changed, 138 insertions, 54 deletions
@@ -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 ---------- diff --git a/doc/conf.py b/doc/conf.py index 0ea50145..23f91419 100644 --- 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 = '' diff --git a/doc/config.rst b/doc/config.rst index 3de76e8d..e1f4c24e 100644 --- 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. diff --git a/doc/templating.rst b/doc/templating.rst index b2812d94..bbb9efff 100644 --- 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. diff --git a/sphinx/builder.py b/sphinx/builder.py index effe9c0a..5c7f4fa4 100644 --- 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): diff --git a/sphinx/config.py b/sphinx/config.py index b1d8aa19..ed2204de 100644 --- 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), diff --git a/sphinx/latexwriter.py b/sphinx/latexwriter.py index f7289d7f..b79f4e15 100644 --- 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( diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 3198f41c..624946c5 100644 --- 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 = '' diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index 5a5ca26c..048a0b83 100644 --- a/sphinx/templates/layout.html +++ b/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" /> diff --git a/sphinx/templates/macros.html b/sphinx/templates/macros.html deleted file mode 100644 index f8a7e8c9..00000000 --- a/sphinx/templates/macros.html +++ /dev/null @@ -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 %} - diff --git a/sphinx/texinputs/howto.cls b/sphinx/texinputs/howto.cls index b77d74d1..f30fffe6 100644 --- 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} diff --git a/sphinx/texinputs/manual.cls b/sphinx/texinputs/manual.cls index a85cd206..a9e76532 100644 --- 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 |