[Python-checkins] r66402 - in doctools/trunk: doc/config.rst sphinx/config.py sphinx/highlighting.py sphinx/latexwriter.py sphinx/texinputs/howto.cls sphinx/texinputs/manual.cls sphinx/texinputs/sphinx.sty
georg.brandl
python-checkins at python.org
Fri Sep 12 15:08:53 CEST 2008
Author: georg.brandl
Date: Fri Sep 12 15:08:52 2008
New Revision: 66402
Log:
Restructure LaTeX file template: add new "latex_elements" config value
allowing to customize each part of what is written to the tex file.
Modified:
doctools/trunk/doc/config.rst
doctools/trunk/sphinx/config.py
doctools/trunk/sphinx/highlighting.py
doctools/trunk/sphinx/latexwriter.py
doctools/trunk/sphinx/texinputs/howto.cls
doctools/trunk/sphinx/texinputs/manual.cls
doctools/trunk/sphinx/texinputs/sphinx.sty
Modified: doctools/trunk/doc/config.rst
==============================================================================
--- doctools/trunk/doc/config.rst (original)
+++ doctools/trunk/doc/config.rst Fri Sep 12 15:08:52 2008
@@ -422,14 +422,6 @@
These options influence LaTeX output.
-.. confval:: latex_paper_size
-
- The output paper size (``'letter'`` or ``'a4'``). Default is ``'letter'``.
-
-.. confval:: latex_font_size
-
- The font size ('10pt', '11pt' or '12pt'). Default is ``'10pt'``.
-
.. confval:: latex_documents
This value determines how to group the document tree into LaTeX source files.
@@ -472,13 +464,91 @@
A list of document names to append as an appendix to all manuals.
-.. confval:: latex_preamble
+.. confval:: latex_use_modindex
- Additional LaTeX markup for the preamble.
+ If true, add a module index to LaTeX documents. Default is ``True``.
+
+.. confval:: latex_elements
+
+ .. versionadded:: 0.5
+
+ A dictionary that contains LaTeX snippets that override those Sphinx usually
+ puts into the generated ``.tex`` files.
Keep in mind that backslashes must be doubled in Python string literals to
avoid interpretation as escape sequences.
-.. confval:: latex_use_modindex
+ * Keys that you may want to override include:
+
+ ``'papersize'``
+ Paper size option of the document class (``'a4paper'`` or
+ ``'letterpaper'``), default ``'letterpaper'``.
+ ``'pointsize'``
+ Point size option of the document class (``'10pt'``, ``'11pt'`` or
+ ``'12pt'``), default ``'10pt'``.
+ ``'babel'``
+ "babel" package inclusion, default ``'\\usepackage{babel}'``.
+ ``'fontpkg'``
+ Font package inclusion, default ``'\\usepackage{times}'`` (which uses
+ Times and Helvetica). You can set this to ``''`` to use the Computer
+ Modern fonts.
+ ``'fncychap'``
+ Inclusion of the "fncychap" package (which makes fancy chapter titles),
+ default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation,
+ ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because
+ the "Bjarne" style uses numbers spelled out in English). Other
+ "fncychap" styles you can try include "Lenny", "Glenn", "Conny" and
+ "Rejne". You can also set this to ``''`` to disable fncychap.
+ ``'preamble'``
+ Additional preamble content, default empty.
+
+ * Keys that don't need be overridden unless in special cases are:
+
+ ``'inputenc'``
+ "inputenc" package inclusion, default ``'\\usepackage[utf8]{inputenc}'``.
+ ``'fontenc'``
+ "fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``.
+ ``'maketitle'``
+ "maketitle" call, default ``'\\maketitle'``. Override if you want to
+ generate a differently-styled title page.
+ ``'tableofcontents'``
+ "tableofcontents" call, default ``'\\tableofcontents'``. Override if you
+ want to generate a different table of contents or put content between the
+ title page and the TOC.
+
+ * Keys that are set by other options and therefore should not be overridden are:
+
+ ``'docclass'``
+ ``'classoptions'``
+ ``'title'``
+ ``'date'``
+ ``'release'``
+ ``'author'``
+ ``'logo'``
+ ``'releasename'``
+ ``'makeindex'``
+ ``'makemodindex'``
+ ``'shorthandoff'``
+ ``'printmodindex'``
+ ``'printindex'``
+
+.. confval:: latex_preamble
- If true, add a module index to LaTeX documents. Default is ``True``.
+ Additional LaTeX markup for the preamble.
+
+ .. deprecated:: 0.5
+ Use the ``'preamble'`` key in the :confval:`latex_elements` value.
+
+.. confval:: latex_paper_size
+
+ The output paper size (``'letter'`` or ``'a4'``). Default is ``'letter'``.
+
+ .. deprecated:: 0.5
+ Use the ``'papersize'`` key in the :confval:`latex_elements` value.
+
+.. confval:: latex_font_size
+
+ The font size ('10pt', '11pt' or '12pt'). Default is ``'10pt'``.
+
+ .. deprecated:: 0.5
+ Use the ``'pointsize'`` key in the :confval:`latex_elements` value.
Modified: doctools/trunk/sphinx/config.py
==============================================================================
--- doctools/trunk/sphinx/config.py (original)
+++ doctools/trunk/sphinx/config.py Fri Sep 12 15:08:52 2008
@@ -75,14 +75,18 @@
htmlhelp_basename = ('pydoc', False),
# LaTeX options
- 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_parts = (False, False),
latex_use_modindex = (True, False),
+ # paper_size and font_size are still separate values
+ # so that you can give them easily on the command line
+ latex_paper_size = ('letter', False),
+ latex_font_size = ('10pt', False),
+ latex_elements = ({}, False),
+ # now deprecated - use latex_elements
+ latex_preamble = ('', False),
)
def __init__(self, dirname, filename, overrides):
Modified: doctools/trunk/sphinx/highlighting.py
==============================================================================
--- doctools/trunk/sphinx/highlighting.py (original)
+++ doctools/trunk/sphinx/highlighting.py Fri Sep 12 15:08:52 2008
@@ -61,15 +61,15 @@
_lexer.add_filter('raiseonerror')
-escape_hl_chars = {ord(u'@'): u'@PYat[]',
- ord(u'['): u'@PYlb[]',
- ord(u']'): u'@PYrb[]'}
+escape_hl_chars = {ord(u'@'): u'@PYGZat[]',
+ ord(u'['): u'@PYGZlb[]',
+ ord(u']'): u'@PYGZrb[]'}
# used if Pygments is not available
_LATEX_STYLES = r'''
-\newcommand\PYat{@}
-\newcommand\PYlb{[}
-\newcommand\PYrb{]}
+\newcommand\PYGZat{@}
+\newcommand\PYGZlb{[}
+\newcommand\PYGZrb{]}
'''
@@ -180,5 +180,11 @@
return _LATEX_STYLES
# no HTML styles needed
return ''
- fmter = (self.dest == 'html' and self.hfmter or self.lfmter)[0]
- return fmter.get_style_defs()
+ if self.dest == 'html':
+ return self.hfmter[0].get_style_defs()
+ else:
+ styledefs = self.lfmter[0].get_style_defs()
+ # workaround for Pygments < 0.12
+ if styledefs.startswith('\\newcommand\\at{@}'):
+ styledefs += _LATEX_STYLES
+ return styledefs
Modified: doctools/trunk/sphinx/latexwriter.py
==============================================================================
--- doctools/trunk/sphinx/latexwriter.py (original)
+++ doctools/trunk/sphinx/latexwriter.py Fri Sep 12 15:08:52 2008
@@ -14,8 +14,8 @@
import re
import sys
-import time
from os import path
+from time import strftime
from docutils import nodes, writers
from docutils.writers.latex2e import Babel
@@ -28,40 +28,38 @@
HEADER = r'''%% Generated by Sphinx.
\documentclass[%(papersize)s,%(pointsize)s%(classoptions)s]{%(docclass)s}
-\usepackage[utf8]{inputenc}
-\usepackage[T1]{fontenc}
-\usepackage{babel}
+%(inputenc)s
+%(fontenc)s
+%(babel)s
+%(fontpkg)s
+%(fncychap)s
+%(preamble)s
+
\title{%(title)s}
\date{%(date)s}
\release{%(release)s}
\author{%(author)s}
\newcommand{\sphinxlogo}{%(logo)s}
\renewcommand{\releasename}{%(releasename)s}
-%(preamble)s
-\makeindex
+%(makeindex)s
+%(makemodindex)s
'''
BEGIN_DOC = r'''
\begin{document}
%(shorthandoff)s
-\maketitle
-\tableofcontents
+%(maketitle)s
+%(tableofcontents)s
'''
FOOTER = r'''
-\printindex
+\renewcommand{\indexname}{%(modindexname)s}
+%(printmodindex)s
+\renewcommand{\indexname}{%(indexname)s}
+%(printindex)s
\end{document}
'''
-GRAPHICX = r'''
-%% Check if we are compiling under latex or pdflatex.
-\ifx\pdftexversion\undefined
- \usepackage{graphicx}
-\else
- \usepackage[pdftex]{graphicx}
-\fi
-'''
-
class LaTeXWriter(writers.Writer):
@@ -118,38 +116,73 @@
ignore_missing_images = False
+ default_elements = {
+ 'docclass': 'manual',
+ 'papersize': 'letterpaper',
+ 'pointsize': '10pt',
+ 'classoptions': '',
+ 'inputenc': '\\usepackage[utf8]{inputenc}',
+ 'fontenc': '\\usepackage[T1]{fontenc}',
+ 'babel': '\\usepackage{babel}',
+ 'fontpkg': '\\usepackage{times}',
+ 'fncychap': '\\usepackage[Bjarne]{fncychap}',
+ 'preamble': '',
+ 'title': '',
+ 'date': '',
+ 'release': '',
+ 'author': '',
+ 'logo': '',
+ 'releasename': 'Release',
+ 'makeindex': '\\makeindex',
+ 'makemodindex': '\\makemodindex',
+ 'shorthandoff': '',
+ 'maketitle': '\\maketitle',
+ 'tableofcontents': '\\tableofcontents',
+ 'printmodindex': '\\printmodindex',
+ 'printindex': '\\printindex',
+ }
+
def __init__(self, document, builder):
nodes.NodeVisitor.__init__(self, document)
self.builder = builder
self.body = []
- docclass = document.settings.docclass
- paper = builder.config.latex_paper_size + 'paper'
- if paper == 'paper': # e.g. command line "-D latex_paper_size="
- paper = 'letterpaper'
- date = time.strftime(builder.config.today_fmt or _('%B %d, %Y'))
- 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,
- 'preamble': builder.config.latex_preamble,
- 'modindex': builder.config.latex_use_modindex,
- 'author': document.settings.author,
- 'docname': document.settings.docname,
- # if empty, the title is set to the first section title
- 'title': document.settings.title,
- 'release': builder.config.release,
- 'releasename': _('Release'),
- 'logo': logo,
- 'date': date,
- 'classoptions': ',english',
- 'shorthandoff': '',
- }
+
+ # sort out some elements
+ papersize = builder.config.latex_paper_size + 'paper'
+ if papersize == 'paper': # e.g. command line "-D latex_paper_size="
+ papersize = 'letterpaper'
+
+ self.elements = self.default_elements.copy()
+ self.elements.update({
+ 'docclass': document.settings.docclass,
+ 'papersize': papersize,
+ 'pointsize': builder.config.latex_font_size,
+ # if empty, the title is set to the first section title
+ 'title': document.settings.title,
+ 'date': strftime(builder.config.today_fmt or _('%B %d, %Y')),
+ 'release': builder.config.release,
+ 'author': document.settings.author,
+ 'releasename': _('Release'),
+ 'preamble': builder.config.latex_preamble,
+ 'modindexname': _('Module Index'),
+ 'indexname': _('Index'),
+ })
+ if builder.config.latex_logo:
+ self.elements['logo'] = '\\includegraphics{%s}\\par' % \
+ path.basename(builder.config.latex_logo)
if builder.config.language:
babel = ExtBabel(builder.config.language)
- self.options['classoptions'] += ',' + babel.get_language()
- self.shorthandoff = babel.get_shorthandoff()
+ self.elements['classoptions'] += ',' + babel.get_language()
+ self.elements['shorthandoff'] = babel.get_shorthandoff()
+ self.elements['fncychap'] = '\\usepackage[Sonny]{fncychap}'
+ else:
+ self.elements['classoptions'] += ',english'
+ if not builder.config.latex_use_modindex:
+ self.elements['makemodindex'] = ''
+ self.elements['printmodindex'] = ''
+ # allow the user to override them all
+ self.elements.update(builder.config.latex_elements)
+
self.highlighter = highlighting.PygmentsBridge(
'latex', builder.config.pygments_style)
self.context = []
@@ -160,7 +193,7 @@
self.highlightlang = builder.config.highlight_language
self.highlightlinenothreshold = sys.maxint
self.written_ids = set()
- if docclass == 'manual':
+ if self.elements['docclass'] == 'manual':
if builder.config.latex_use_parts:
self.top_sectionlevel = 0
else:
@@ -175,25 +208,15 @@
self.first_document = 1
self.this_is_the_title = 1
self.literal_whitespace = 0
- self.need_graphicx = 0
def astext(self):
- return (HEADER % self.options) + \
- (self.options['modindex'] and '\\makemodindex\n' or '') + \
- self.highlighter.get_stylesheet() + \
- (self.need_graphicx and GRAPHICX or '') + \
- '\n\n' + \
- u''.join(self.body) + \
- (self.options['modindex'] and
- ('\\renewcommand{\\indexname}{%s}' % _('Module Index') +
- '\\printmodindex' +
- '\\renewcommand{\\indexname}{%s}\n' % _('Index')) or '') + \
- (FOOTER % self.options)
+ return (HEADER % self.elements + self.highlighter.get_stylesheet() +
+ u''.join(self.body) + FOOTER % self.elements)
def visit_document(self, node):
if self.first_document == 1:
# the first document is all the regular content ...
- self.body.append(BEGIN_DOC)
+ self.body.append(BEGIN_DOC % self.elements)
self.first_document = 0
elif self.first_document == 0:
# ... and all others are the appendices
@@ -288,8 +311,8 @@
elif self.this_is_the_title:
if len(node.children) != 1 and not isinstance(node.children[0], nodes.Text):
self.builder.warn('document title is not a single Text node')
- if not self.options['title']:
- self.options['title'] = node.astext()
+ if not self.elements['title']:
+ self.elements['title'] = node.astext()
self.this_is_the_title = 0
raise nodes.SkipNode
elif isinstance(node.parent, nodes.section):
@@ -649,7 +672,6 @@
return res
def visit_image(self, node):
- self.need_graphicx = 1
attrs = node.attributes
pre = [] # in reverse order
post = []
@@ -825,7 +847,7 @@
if self.in_title or not uri:
self.context.append('')
elif uri.startswith('mailto:') or uri.startswith('http:') or \
- uri.startswith('ftp:'):
+ uri.startswith('https:') or uri.startswith('ftp:'):
self.body.append('\\href{%s}{' % self.encode(uri))
self.context.append('}')
elif uri.startswith('#'):
Modified: doctools/trunk/sphinx/texinputs/howto.cls
==============================================================================
--- doctools/trunk/sphinx/texinputs/howto.cls (original)
+++ doctools/trunk/sphinx/texinputs/howto.cls Fri Sep 12 15:08:52 2008
@@ -3,7 +3,7 @@
%
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{howto}[2008/05/01 Document class (Sphinx HOWTO)]
+\ProvidesClass{howto}[2008/09/12 Document class (Sphinx HOWTO)]
\RequirePackage{fancybox}
@@ -12,18 +12,11 @@
\ProcessOptions\relax
\LoadClass[twoside]{article}
-
% Set some sane defaults for section numbering depth and TOC depth. You can
% reset these counters in your preamble.
%
\setcounter{secnumdepth}{2}
-
-% The "fancyhdr" package makes nicer page footers reasonable to implement, and
-% is used to put the chapter and section information in the footers.
-%
-\RequirePackage{fancyhdr}
-
% This gives us all the Python-specific markup that we really want. This should
% come last. Do not change this.
%
@@ -34,15 +27,12 @@
%
\RequirePackage{makeidx}
-% Need to do one of these....
-\newcommand{\py at doHorizontalRule}{\rule{\textwidth}{1pt}}
-
% Change the title page to look a bit better, and fit in with the fncychap
% ``Bjarne'' style a bit better.
%
\renewcommand{\maketitle}{
- \py at doHorizontalRule
+ \rule{\textwidth}{1pt}
\ifpdf
\begingroup
% This \def is required to deal with multi-line authors; it
@@ -78,7 +68,7 @@
\parskip = 0mm
\py at OldTableofcontents
\endgroup
- \py at doHorizontalRule
+ \rule{\textwidth}{1pt}
\vspace{12pt}
}
Modified: doctools/trunk/sphinx/texinputs/manual.cls
==============================================================================
--- doctools/trunk/sphinx/texinputs/manual.cls (original)
+++ doctools/trunk/sphinx/texinputs/manual.cls Fri Sep 12 15:08:52 2008
@@ -3,7 +3,7 @@
%
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesClass{manual}[2008/05/01 Document class (Sphinx manual)]
+\ProvidesClass{manual}[2008/09/12 Document class (Sphinx manual)]
\RequirePackage{fancybox}
@@ -12,25 +12,12 @@
\ProcessOptions\relax
\LoadClass[twoside,openright]{report}
-
% Set some sane defaults for section numbering depth and TOC depth. You can
% reset these counters in your preamble.
%
\setcounter{secnumdepth}{2}
\setcounter{tocdepth}{1}
-
-% The "fancyhdr" package makes nicer page footers reasonable to implement, and
-% is used to put the chapter and section information in the footers.
-%
-\RequirePackage{fancyhdr}
-
-% The "fncychap" package is used to get the nice chapter headers.
-%
-\RequirePackage[Bjarne]{fncychap}
-% Do horizontal rules it this way to match:
-\newcommand{\py at doHorizontalRule}{\mghrulefill{\RW}}
-
% This gives us all the Sphinx-specific markup that we really want. This should
% come last. Do not change this.
%
@@ -49,7 +36,7 @@
\begin{titlepage}%
\let\footnotesize\small
\let\footnoterule\relax
- \py at doHorizontalRule%
+ \rule{\textwidth}{1pt}%
\ifpdf
\begingroup
% This \def is required to deal with multi-line authors; it
Modified: doctools/trunk/sphinx/texinputs/sphinx.sty
==============================================================================
--- doctools/trunk/sphinx/texinputs/sphinx.sty (original)
+++ doctools/trunk/sphinx/texinputs/sphinx.sty Fri Sep 12 15:08:52 2008
@@ -9,8 +9,8 @@
\ProvidesPackage{sphinx}[2008/05/01 LaTeX package (Sphinx markup)]
\RequirePackage{textcomp}
-\RequirePackage{times}
\RequirePackage{fancyvrb}
+\RequirePackage{fancyhdr}
\RequirePackage{titlesec}
\RequirePackage{tabulary}
\RequirePackage{amsmath} % for \text
@@ -36,18 +36,19 @@
\RequirePackage{framed}
-\ifx\pdftexversion\undefined
- \RequirePackage{graphicx}
-\else
- \RequirePackage[pdftex]{graphicx}
-\fi
-
% Uncomment these two lines to ignore the paper size and make the page
% size more like a typical published manual.
%\renewcommand{\paperheight}{9in}
%\renewcommand{\paperwidth}{8.5in} % typical squarish manual
%\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python''
+% For graphicx, check if we are compiling under latex or pdflatex.
+\ifx\pdftexversion\undefined
+ \usepackage{graphicx}
+\else
+ \usepackage[pdftex]{graphicx}
+\fi
+
% for PDF output, use maximal compression
\newif\ifpdf\pdffalse
\ifx\pdfoutput\undefined\else\ifcase\pdfoutput
More information about the Python-checkins
mailing list