RedHatTraining/pyramid.git

Chris McDonough

2010-12-20 bd3bf1423ab441ccdca2b7e05cdb2b1b94c12223

commit \| author \| age
f70c23	1	# -- coding: utf-8 --
CM	2	#
edd915	3	# pyramid documentation build configuration file, created by
f70c23	4	# sphinx-quickstart on Wed Jul 16 13:18:14 2008.
CM	5	#
	6	# This file is execfile()d with the current directory set to its containing dir.
	7	#
	8	# The contents of this file are pickled, so don't put values in the namespace
	9	# that aren't pickleable (module imports are okay, they're removed automatically).
	10	#
	11	# All configuration values have a default value; values that are commented out
	12	# serve to show the default value.
	13
	14	import sys, os
52d4fb	15	import datetime
50fb10	16	import warnings
CM	17
	18	warnings.simplefilter('ignore', DeprecationWarning)
f70c23	19
6cdedf	20	# skip raw nodes
CM	21	from sphinx.writers.text import TextTranslator
43889a	22	from sphinx.writers.latex import LaTeXTranslator
CM	23
6cdedf	24	from docutils import nodes
fd5ae9	25	from docutils import utils
CM	26
6cdedf	27	def raw(*arg):
CM	28	raise nodes.SkipNode
	29	TextTranslator.visit_raw = raw
	30
43889a	31
CM	32	# make sure :app:`Pyramid` doesn't mess up LaTeX rendering
	33	def nothing(*arg):
	34	pass
	35	LaTeXTranslator.visit_inline = nothing
	36	LaTeXTranslator.depart_inline = nothing
	37
d22e8d	38	book = os.environ.get('BOOK')
274778	39
f70c23	40	# If your extensions are in another directory, add it here. If the directory
CM	41	# is relative to the documentation root, use os.path.abspath to make it
	42	# absolute, like shown here.
9974be	43	parent = os.path.dirname(os.path.dirname(__file__))
CM	44	sys.path.append(os.path.abspath(parent))
	45	wd = os.getcwd()
	46	os.chdir(parent)
	47	os.system('%s setup.py test -q' % sys.executable)
	48	os.chdir(wd)
	49
	50	for item in os.listdir(parent):
	51	if item.endswith('.egg'):
	52	sys.path.append(os.path.join(parent, item))
f70c23	53
CM	54	# General configuration
	55	# ---------------------
	56
	57	# Add any Sphinx extension module names here, as strings. They can be extensions
	58	# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
51b2f9	59	extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
CM	60	'repoze.sphinx.autointerface']
f70c23	61
CM	62	# Add any paths that contain templates here, relative to this directory.
785d2f	63	templates_path = ['_templates']
f70c23	64
CM	65	# The suffix of source filenames.
	66	source_suffix = '.rst'
	67
	68	# The master toctree document.
	69	master_doc = 'index'
	70
	71	# General substitutions.
edd915	72	project = 'The Pyramid Web Application Development Framework'
52d4fb	73	copyright = '%s, Agendaless Consulting' % datetime.datetime.now().year
f70c23	74
CM	75	# The default replacements for \|version\| and \|release\|, also used in various
	76	# other places throughout the built documents.
	77	#
	78	# The short X.Y version.
bd3bf1	79	version = '1.0a7'
f70c23	80	# The full version, including alpha/beta/rc tags.
c0114e	81	release = version
f70c23	82
CM	83	# There are two options for replacing \|today\|: either, you set today to some
	84	# non-false value, then it is used:
	85	#today = ''
	86	# Else, today_fmt is used as the format for a strftime call.
	87	today_fmt = '%B %d, %Y'
	88
	89	# List of documents that shouldn't be included in the build.
	90	#unused_docs = []
	91
	92	# List of directories, relative to source directories, that shouldn't be searched
	93	# for source files.
	94	#exclude_dirs = []
	95
	96	# The reST default role (used for this markup: `text`) to use for all documents.
	97	#default_role = None
	98
	99	# If true, '()' will be appended to :func: etc. cross-reference text.
	100	#add_function_parentheses = True
	101
	102	# If true, the current module name will be prepended to all description
	103	# unit titles (such as .. function::).
e4e3aa	104	add_module_names = False
f70c23	105
CM	106	# If true, sectionauthor and moduleauthor directives will be shown in the
	107	# output. They are ignored by default.
	108	#show_authors = False
	109
	110	# The name of the Pygments (syntax highlighting) style to use.
957548	111	#pygments_style = book and 'bw' or 'tango'
5845bc	112	if book:
CM	113	pygments_style = 'bw'
f70c23	114
002c0c	115	# The default language to highlight source code in.
cc19a8	116	#highlight_language = 'guess'
002c0c	117
f70c23	118	# Options for HTML output
CM	119	# -----------------------
	120
957548	121	# Add and use Pylons theme
BL	122	sys.path.append(os.path.abspath('_themes'))
	123	html_theme_path = ['_themes']
cc19a8	124	html_theme = 'pyramid'
785d2f	125
f70c23	126	# The style sheet to use for HTML and HTML Help pages. A file of that name
CM	127	# must exist either in Sphinx' static/ path, or in one of the custom paths
	128	# given in html_static_path.
957548	129	#html_style = 'pyramid.css'
f70c23	130
CM	131	# The name for this set of Sphinx documents. If None, it defaults to
	132	# "<project> v<release> documentation".
785d2f	133	html_title = 'The Pyramid Web Application Development Framework v%s' % release
f70c23	134
CM	135	# A shorter title for the navigation bar. Default is the same as html_title.
cc19a8	136	#html_short_title = 'Home'
f70c23	137
CM	138	# The name of an image file (within the static path) to place at the top of
	139	# the sidebar.
cc19a8	140	#html_logo = '_static/pyramid.png'
f70c23	141
CM	142	# The name of an image file (within the static path) to use as favicon of the
	143	# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
	144	# pixels large.
cc19a8	145	#html_favicon = '_static/pyramid.ico'
f70c23	146
CM	147	# Add any paths that contain custom static files (such as style sheets) here,
	148	# relative to this directory. They are copied after the builtin static files,
	149	# so a file named "default.css" will overwrite the builtin "default.css".
cc19a8	150	#html_static_path = ['_static']
f70c23	151
CM	152	# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
	153	# using the given strftime format.
	154	html_last_updated_fmt = '%b %d, %Y'
	155
	156	# If true, SmartyPants will be used to convert quotes and dashes to
	157	# typographically correct entities.
	158	#html_use_smartypants = True
	159
	160	# Custom sidebar templates, maps document names to template names.
	161	#html_sidebars = {}
	162
	163	# Additional templates that should be rendered to pages, maps page names to
	164	# template names.
	165	#html_additional_pages = {}
	166
	167	# If false, no module index is generated.
	168	#html_use_modindex = True
	169
	170	# If false, no index is generated.
	171	#html_use_index = True
	172
	173	# If true, the index is split into individual pages for each letter.
	174	#html_split_index = False
	175
	176	# If true, the reST sources are included in the HTML build as _sources/<name>.
	177	#html_copy_source = True
	178
	179	# If true, an OpenSearch description file will be output, and all pages will
	180	# contain a <link> tag referring to it. The value of this option must be the
	181	# base URL from which the finished HTML is served.
	182	#html_use_opensearch = ''
	183
	184	# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
	185	#html_file_suffix = ''
	186
	187	# Output file base name for HTML help builder.
71ff10	188	htmlhelp_basename = 'pyramid'
f70c23	189
CM	190	# Options for LaTeX output
	191	# ------------------------
	192
	193	# The paper size ('letter' or 'a4').
67bfd8	194	latex_paper_size = 'letter'
f70c23	195
CM	196	# The font size ('10pt', '11pt' or '12pt').
67bfd8	197	latex_font_size = '10pt'
f70c23	198
CM	199	# Grouping the document tree into LaTeX files. List of tuples
	200	# (source start file, target name, title, author, document class [howto/manual]).
	201	latex_documents = [
71ff10	202	('latexindex', 'pyramid.tex',
edd915	203	'The Pyramid Web Application Development Framework',
8be78e	204	'Chris McDonough', 'manual'),
CM	205	]
f70c23	206
CM	207	# The name of an image file (relative to this directory) to place at the top of
	208	# the title page.
cc19a8	209	#latex_logo = '_static/pylons_small.png'
f70c23	210
CM	211	# For "manual" documents, if this is true, then toplevel headings are parts,
	212	# not chapters.
67bfd8	213	latex_use_parts = True
f70c23	214
CM	215	# Additional stuff for the LaTeX preamble.
	216	#latex_preamble = ''
	217
	218	# Documents to append as an appendix to all manuals.
	219	#latex_appendices = []
	220
	221	# If false, no module index is generated.
7a3985	222	latex_use_modindex = False
125e97	223
CM	224	## Say, for a moment that you have a twoside document that needs a 3cm
	225	## inner margin to allow for binding and at least two centimetres the
	226	## rest of the way around. You've been using the a4wide package up until
	227	## now, because you like the amount of text it places on the
	228	## page. Perhaps try something like this in your preamble:
	229
	230	## \usepackage[bindingoffset=1cm,textheight=22cm,hdivide={2cm,,2cm},vdivide={,22cm,*}]{geometry}
	231
f2086c	232	## _PREAMBLE = r"""\usepackage[bindingoffset=0.45in,textheight=7.25in,hdivide={0.5in,*,0.75in},vdivide={1in,7.25in,1in},papersize={7.5in,9.25in}]{geometry}"""
125e97	233
f2086c	234	_PREAMBLE = r"""
CM	235	\usepackage[]{geometry}
	236	\geometry{bindingoffset=0.45in,textheight=7.25in,hdivide={0.5in,*,0.75in},vdivide={1in,7.25in,1in},papersize={7.5in,9.25in}}
	237	\hypersetup{
	238	colorlinks=true,
	239	linkcolor=black,
	240	citecolor=black,
	241	filecolor=black,
	242	urlcolor=black
	243	}
274778	244	\fvset{frame=single,xleftmargin=9pt,numbersep=4pt}
f2086c	245
CM	246	\pagestyle{fancy}
	247
9ec2d6	248	% header and footer styles
f2086c	249	\renewcommand{\chaptermark}[1]%
9ec2d6	250	{\markboth{\MakeUppercase{\thechapter.\ #1}}{}
CM	251	}
f2086c	252	\renewcommand{\sectionmark}[1]%
9ec2d6	253	{\markright{\MakeUppercase{\thesection.\ #1}}
CM	254	}
	255
	256	% defaults for fancy style
	257	\renewcommand{\headrulewidth}{0pt}
f2086c	258	\renewcommand{\footrulewidth}{0pt}
CM	259	\fancyhf{}
	260	\fancyfoot[C]{\thepage}
	261
9ec2d6	262	% plain style
f2086c	263	\fancypagestyle{plain}{
CM	264	\renewcommand{\headrulewidth}{0pt} % ho header line
9ec2d6	265	\renewcommand{\footrulewidth}{0pt}% no footer line
CM	266	\fancyhf{} % empty header and footer
	267	\fancyfoot[C]{\thepage}
f2086c	268	}
3a4e6f	269
9ec2d6	270	% title page styles
3a4e6f	271	\makeatletter
CM	272	\def\@subtitle{\relax}
	273	\newcommand{\subtitle}[1]{\gdef\@subtitle{#1}}
	274	\renewcommand{\maketitle}{
	275	\begin{titlepage}
	276	{\rm\Huge\@title\par}
	277	{\em\large\py@release\releaseinfo\par}
	278	\if\@subtitle\relax\else\large\@subtitle\par\fi
	279	{\large\@author\par}
	280	\end{titlepage}
	281	}
	282	\makeatother
	283
9ec2d6	284	% Redefine link and title colors
793425	285	\definecolor{TitleColor}{rgb}{0,0,0}
CM	286	\definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486}
	287	\definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388}
	288	% Redefine these colors to something not white if you want to have colored
	289	% background and border for code examples.
	290	\definecolor{VerbatimColor}{rgb}{1,1,1}
	291	\definecolor{VerbatimBorderColor}{rgb}{1,1,1}
	292
	293	\makeatletter
dc0ba7	294	\renewcommand{\py@noticestart@warning}{\py@heavybox}
CM	295	\renewcommand{\py@noticeend@warning}{\py@endheavybox}
793425	296	\renewcommand{\py@noticestart@note}{\py@heavybox}
CM	297	\renewcommand{\py@noticeend@note}{\py@endheavybox}
	298	\makeatother
	299
9ec2d6	300	% icons in note and warning boxes
dc0ba7	301	\usepackage{ifthen}
CM	302	% Keep a copy of the original notice environment
	303	\let\origbeginnotice\notice
	304	\let\origendnotice\endnotice
	305
	306	% Redefine the notice environment so we can add our own code to it
	307	\renewenvironment{notice}[2]{%
	308	\origbeginnotice{#1}{}% equivalent to original \begin{notice}{#1}{#2}
	309	% load graphics
de8c1b	310	\ifthenelse{\equal{#1}{warning}}{\includegraphics{latex-warning.png}}{}
BL	311	\ifthenelse{\equal{#1}{note}}{\includegraphics{latex-note.png}}{}
dc0ba7	312	% etc.
CM	313	}{%
	314	\origendnotice% equivalent to original \end{notice}
	315	}
	316
9ec2d6	317	% try to prevent code-block boxes from splitting across pages
44f1df	318	\sloppy
9ec2d6	319	\widowpenalty=300
CM	320	\clubpenalty=300
	321	\setlength{\parskip}{3ex plus 2ex minus 2ex}
	322
	323	% suppress page numbers on pages showing part title
	324	\makeatletter
	325	\let\sv@endpart\@endpart
	326	\def\@endpart{\thispagestyle{empty}\sv@endpart}
	327	\makeatother
	328
	329	% prevent page numbers in TOC (reset to fancy by frontmatter directive)
	330	\pagestyle{empty}
f2086c	331	"""
125e97	332
CM	333	latex_elements = {
f2086c	334	'preamble': _PREAMBLE,
CM	335	'wrapperclass':'book',
d22e8d	336	'date':'',
3a4e6f	337	'releasename':'Version',
edd915	338	'title':r'The Pyramid Web Application \newline Development Framework',
9544d0	339	# 'pointsize':'12pt', # uncomment for 12pt version
f2086c	340	}
CM	341
9ec2d6	342	# secnumdepth counter reset to 2 causes numbering in related matter;
CM	343	# reset to -1 causes chapters to not be numbered, reset to -2 causes
	344	# parts to not be numbered.
	345
	346	#part -1
	347	#chapter 0
	348	#section 1
	349	#subsection 2
	350	#subsubsection 3
	351	#paragraph 4
	352	#subparagraph 5
	353
f2086c	354	def frontmatter(name, arguments, options, content, lineno,
CM	355	content_offset, block_text, state, state_machine):
9ec2d6	356	return [nodes.raw(
CM	357	'',
	358	r"""
	359	\frontmatter
	360	% prevent part/chapter/section numbering
	361	\setcounter{secnumdepth}{-2}
	362	% suppress headers
	363	\pagestyle{plain}
	364	% reset page counter
	365	\setcounter{page}{1}
	366	% suppress first toc pagenum
	367	\addtocontents{toc}{\protect\thispagestyle{empty}}
	368	""",
	369	format='latex')]
f2086c	370
CM	371	def mainmatter(name, arguments, options, content, lineno,
	372	content_offset, block_text, state, state_machine):
9ec2d6	373	return [nodes.raw(
CM	374	'',
	375	r"""
	376	\mainmatter
	377	% allow part/chapter/section numbering
	378	\setcounter{secnumdepth}{2}
	379	% get headers back
	380	\pagestyle{fancy}
	381	\fancyhf{}
	382	\renewcommand{\headrulewidth}{0.5pt}
	383	\renewcommand{\footrulewidth}{0pt}
	384	\fancyfoot[C]{\thepage}
	385	\fancyhead[RO]{\rightmark}
	386	\fancyhead[LE]{\leftmark}
	387	""",
	388	format='latex')]
f2086c	389
CM	390	def backmatter(name, arguments, options, content, lineno,
	391	content_offset, block_text, state, state_machine):
9ec2d6	392	return [nodes.raw('', '\\backmatter\n\\setcounter{secnumdepth}{-1}\n',
CM	393	format='latex')]
f2086c	394
fd5ae9	395	def app_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
CM	396	"""custom role for :app: marker, does nothing in particular except allow
	397	:app:`Pyramid` to work (for later search and replace)."""
	398	if 'class' in options:
	399	assert 'classes' not in options
	400	options['classes'] = options['class']
	401	del options['class']
	402	return [nodes.inline(rawtext, utils.unescape(text), **options)], []
	403
	404
f2086c	405	def setup(app):
fd5ae9	406	app.add_role('app', app_role)
f2086c	407	app.add_directive('frontmatter', frontmatter, 1, (0, 0, 0))
CM	408	app.add_directive('mainmatter', mainmatter, 1, (0, 0, 0))
	409	app.add_directive('backmatter', backmatter, 1, (0, 0, 0))
016a1f	410
274778	411	# turn off all line numbers in latex formatting
CM	412
	413	## from pygments.formatters import LatexFormatter
	414	## from sphinx.highlighting import PygmentsBridge
	415
	416	## class NoLinenosLatexFormatter(LatexFormatter):
	417	## def __init__(self, **options):
	418	## LatexFormatter.__init__(self, **options)
	419	## self.linenos = False
	420
	421	## PygmentsBridge.latex_formatter = NoLinenosLatexFormatter
6d47bc	422
CM	423	# -- Options for Epub output ---------------------------------------------------
	424
	425	# Bibliographic Dublin Core info.
edd915	426	epub_title = 'The Pyramid Web Application Development Framework, Version 1.0'
6d47bc	427	epub_author = 'Chris McDonough'
CM	428	epub_publisher = 'Agendaless Consulting'
	429	epub_copyright = '2008-2010'
	430
	431	# The language of the text. It defaults to the language option
	432	# or en if the language is not set.
	433	epub_language = 'en'
	434
	435	# The scheme of the identifier. Typical schemes are ISBN or URL.
	436	epub_scheme = 'ISBN'
	437
	438	# The unique identifier of the text. This can be a ISBN number
	439	# or the project homepage.
	440	epub_identifier = '0615345379'
	441
	442	# A unique identification for the text.
edd915	443	epub_uid = 'The Pyramid Web Application Development Framework, Version 1.0'
6d47bc	444
CM	445	# HTML files that should be inserted before the pages created by sphinx.
	446	# The format is a list of tuples containing the path and title.
	447	#epub_pre_files = []
	448
	449	# HTML files shat should be inserted after the pages created by sphinx.
	450	# The format is a list of tuples containing the path and title.
	451	#epub_post_files = []
	452
	453	# A list of files that should not be packed into the epub file.
	454	#epub_exclude_files = []
	455
	456	# The depth of the table of contents in toc.ncx.
	457	epub_tocdepth = 3