RedHatTraining/pyramid.git

Chris McDonough

2010-11-16 3fa99493e9ba3d1dc05d8e917ee2f1bc1b6ed14e

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