RedHatTraining/pyramid.git

Chris McDonough

2011-01-22 a44845ef92567c90ba8d163f0cb5203151243001

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