[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
georg.brandl
python-checkins at python.org
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 ' »' 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
More information about the Python-checkins
mailing list