RedHatTraining/pyramid.git

Chris McDonough

2011-08-29 21a4c9b232b2d5c9660f27904b92645b109eda15

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',
288072	64	# 'sphinx.ext.intersphinx'
8864e0	65	]
CM	66
	67	# Looks for objects in other Pyramid projects
288072	68	## intersphinx_mapping = {
CM	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.
21a4c9	96	version = '1.2a3'
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
82ec1b	143	html_theme_options = {
BL	144	'github_url': 'https://github.com/Pylons/pyramid'
	145	}
	146
f70c23	147	# The style sheet to use for HTML and HTML Help pages. A file of that name
CM	148	# must exist either in Sphinx' static/ path, or in one of the custom paths
	149	# given in html_static_path.
957548	150	#html_style = 'pyramid.css'
f70c23	151
CM	152	# The name for this set of Sphinx documents. If None, it defaults to
	153	# "<project> v<release> documentation".
785d2f	154	html_title = 'The Pyramid Web Application Development Framework v%s' % release
f70c23	155
CM	156	# A shorter title for the navigation bar. Default is the same as html_title.
cc19a8	157	#html_short_title = 'Home'
f70c23	158
CM	159	# The name of an image file (within the static path) to place at the top of
	160	# the sidebar.
cc19a8	161	#html_logo = '_static/pyramid.png'
f70c23	162
CM	163	# The name of an image file (within the static path) to use as favicon of the
	164	# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
	165	# pixels large.
cc19a8	166	#html_favicon = '_static/pyramid.ico'
f70c23	167
CM	168	# Add any paths that contain custom static files (such as style sheets) here,
	169	# relative to this directory. They are copied after the builtin static files,
	170	# so a file named "default.css" will overwrite the builtin "default.css".
cc19a8	171	#html_static_path = ['_static']
f70c23	172
CM	173	# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
	174	# using the given strftime format.
	175	html_last_updated_fmt = '%b %d, %Y'
	176
	177	# If true, SmartyPants will be used to convert quotes and dashes to
	178	# typographically correct entities.
	179	#html_use_smartypants = True
	180
	181	# Custom sidebar templates, maps document names to template names.
	182	#html_sidebars = {}
	183
	184	# Additional templates that should be rendered to pages, maps page names to
	185	# template names.
	186	#html_additional_pages = {}
	187
	188	# If false, no module index is generated.
	189	#html_use_modindex = True
	190
	191	# If false, no index is generated.
	192	#html_use_index = True
	193
	194	# If true, the index is split into individual pages for each letter.
	195	#html_split_index = False
	196
	197	# If true, the reST sources are included in the HTML build as _sources/<name>.
	198	#html_copy_source = True
	199
	200	# If true, an OpenSearch description file will be output, and all pages will
	201	# contain a <link> tag referring to it. The value of this option must be the
	202	# base URL from which the finished HTML is served.
	203	#html_use_opensearch = ''
	204
	205	# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
	206	#html_file_suffix = ''
	207
	208	# Output file base name for HTML help builder.
71ff10	209	htmlhelp_basename = 'pyramid'
f70c23	210
CM	211	# Options for LaTeX output
	212	# ------------------------
	213
	214	# The paper size ('letter' or 'a4').
67bfd8	215	latex_paper_size = 'letter'
f70c23	216
CM	217	# The font size ('10pt', '11pt' or '12pt').
67bfd8	218	latex_font_size = '10pt'
f70c23	219
CM	220	# Grouping the document tree into LaTeX files. List of tuples
	221	# (source start file, target name, title, author, document class [howto/manual]).
	222	latex_documents = [
71ff10	223	('latexindex', 'pyramid.tex',
edd915	224	'The Pyramid Web Application Development Framework',
8be78e	225	'Chris McDonough', 'manual'),
CM	226	]
f70c23	227
CM	228	# The name of an image file (relative to this directory) to place at the top of
	229	# the title page.
cc19a8	230	#latex_logo = '_static/pylons_small.png'
f70c23	231
CM	232	# For "manual" documents, if this is true, then toplevel headings are parts,
	233	# not chapters.
67bfd8	234	latex_use_parts = True
f70c23	235
CM	236	# Additional stuff for the LaTeX preamble.
	237	#latex_preamble = ''
	238
	239	# Documents to append as an appendix to all manuals.
	240	#latex_appendices = []
	241
	242	# If false, no module index is generated.
7a3985	243	latex_use_modindex = False
125e97	244
CM	245	## Say, for a moment that you have a twoside document that needs a 3cm
	246	## inner margin to allow for binding and at least two centimetres the
	247	## rest of the way around. You've been using the a4wide package up until
	248	## now, because you like the amount of text it places on the
	249	## page. Perhaps try something like this in your preamble:
	250
	251	## \usepackage[bindingoffset=1cm,textheight=22cm,hdivide={2cm,,2cm},vdivide={,22cm,*}]{geometry}
	252
f2086c	253	## _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	254
f2086c	255	_PREAMBLE = r"""
CM	256	\usepackage[]{geometry}
	257	\geometry{bindingoffset=0.45in,textheight=7.25in,hdivide={0.5in,*,0.75in},vdivide={1in,7.25in,1in},papersize={7.5in,9.25in}}
	258	\hypersetup{
	259	colorlinks=true,
	260	linkcolor=black,
	261	citecolor=black,
	262	filecolor=black,
	263	urlcolor=black
	264	}
274778	265	\fvset{frame=single,xleftmargin=9pt,numbersep=4pt}
f2086c	266
CM	267	\pagestyle{fancy}
	268
9ec2d6	269	% header and footer styles
f2086c	270	\renewcommand{\chaptermark}[1]%
9ec2d6	271	{\markboth{\MakeUppercase{\thechapter.\ #1}}{}
CM	272	}
f2086c	273	\renewcommand{\sectionmark}[1]%
9ec2d6	274	{\markright{\MakeUppercase{\thesection.\ #1}}
CM	275	}
	276
	277	% defaults for fancy style
	278	\renewcommand{\headrulewidth}{0pt}
f2086c	279	\renewcommand{\footrulewidth}{0pt}
CM	280	\fancyhf{}
	281	\fancyfoot[C]{\thepage}
	282
9ec2d6	283	% plain style
f2086c	284	\fancypagestyle{plain}{
CM	285	\renewcommand{\headrulewidth}{0pt} % ho header line
9ec2d6	286	\renewcommand{\footrulewidth}{0pt}% no footer line
CM	287	\fancyhf{} % empty header and footer
	288	\fancyfoot[C]{\thepage}
f2086c	289	}
3a4e6f	290
9ec2d6	291	% title page styles
3a4e6f	292	\makeatletter
CM	293	\def\@subtitle{\relax}
	294	\newcommand{\subtitle}[1]{\gdef\@subtitle{#1}}
	295	\renewcommand{\maketitle}{
	296	\begin{titlepage}
	297	{\rm\Huge\@title\par}
	298	{\em\large\py@release\releaseinfo\par}
	299	\if\@subtitle\relax\else\large\@subtitle\par\fi
	300	{\large\@author\par}
	301	\end{titlepage}
	302	}
	303	\makeatother
	304
9ec2d6	305	% Redefine link and title colors
793425	306	\definecolor{TitleColor}{rgb}{0,0,0}
CM	307	\definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486}
	308	\definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388}
	309	% Redefine these colors to something not white if you want to have colored
	310	% background and border for code examples.
	311	\definecolor{VerbatimColor}{rgb}{1,1,1}
	312	\definecolor{VerbatimBorderColor}{rgb}{1,1,1}
	313
	314	\makeatletter
dc0ba7	315	\renewcommand{\py@noticestart@warning}{\py@heavybox}
CM	316	\renewcommand{\py@noticeend@warning}{\py@endheavybox}
793425	317	\renewcommand{\py@noticestart@note}{\py@heavybox}
CM	318	\renewcommand{\py@noticeend@note}{\py@endheavybox}
	319	\makeatother
	320
9ec2d6	321	% icons in note and warning boxes
dc0ba7	322	\usepackage{ifthen}
CM	323	% Keep a copy of the original notice environment
	324	\let\origbeginnotice\notice
	325	\let\origendnotice\endnotice
	326
	327	% Redefine the notice environment so we can add our own code to it
	328	\renewenvironment{notice}[2]{%
	329	\origbeginnotice{#1}{}% equivalent to original \begin{notice}{#1}{#2}
	330	% load graphics
de8c1b	331	\ifthenelse{\equal{#1}{warning}}{\includegraphics{latex-warning.png}}{}
BL	332	\ifthenelse{\equal{#1}{note}}{\includegraphics{latex-note.png}}{}
dc0ba7	333	% etc.
CM	334	}{%
	335	\origendnotice% equivalent to original \end{notice}
	336	}
	337
9ec2d6	338	% try to prevent code-block boxes from splitting across pages
44f1df	339	\sloppy
9ec2d6	340	\widowpenalty=300
CM	341	\clubpenalty=300
	342	\setlength{\parskip}{3ex plus 2ex minus 2ex}
	343
	344	% suppress page numbers on pages showing part title
	345	\makeatletter
	346	\let\sv@endpart\@endpart
	347	\def\@endpart{\thispagestyle{empty}\sv@endpart}
	348	\makeatother
	349
	350	% prevent page numbers in TOC (reset to fancy by frontmatter directive)
	351	\pagestyle{empty}
f2086c	352	"""
125e97	353
CM	354	latex_elements = {
f2086c	355	'preamble': _PREAMBLE,
CM	356	'wrapperclass':'book',
d22e8d	357	'date':'',
3a4e6f	358	'releasename':'Version',
edd915	359	'title':r'The Pyramid Web Application \newline Development Framework',
9544d0	360	# 'pointsize':'12pt', # uncomment for 12pt version
f2086c	361	}
CM	362
9ec2d6	363	# secnumdepth counter reset to 2 causes numbering in related matter;
CM	364	# reset to -1 causes chapters to not be numbered, reset to -2 causes
	365	# parts to not be numbered.
	366
	367	#part -1
	368	#chapter 0
	369	#section 1
	370	#subsection 2
	371	#subsubsection 3
	372	#paragraph 4
	373	#subparagraph 5
	374
f2086c	375	def frontmatter(name, arguments, options, content, lineno,
CM	376	content_offset, block_text, state, state_machine):
9ec2d6	377	return [nodes.raw(
CM	378	'',
	379	r"""
	380	\frontmatter
	381	% prevent part/chapter/section numbering
	382	\setcounter{secnumdepth}{-2}
	383	% suppress headers
	384	\pagestyle{plain}
	385	% reset page counter
	386	\setcounter{page}{1}
	387	% suppress first toc pagenum
	388	\addtocontents{toc}{\protect\thispagestyle{empty}}
	389	""",
	390	format='latex')]
f2086c	391
CM	392	def mainmatter(name, arguments, options, content, lineno,
	393	content_offset, block_text, state, state_machine):
9ec2d6	394	return [nodes.raw(
CM	395	'',
	396	r"""
	397	\mainmatter
	398	% allow part/chapter/section numbering
	399	\setcounter{secnumdepth}{2}
	400	% get headers back
	401	\pagestyle{fancy}
	402	\fancyhf{}
	403	\renewcommand{\headrulewidth}{0.5pt}
	404	\renewcommand{\footrulewidth}{0pt}
	405	\fancyfoot[C]{\thepage}
	406	\fancyhead[RO]{\rightmark}
	407	\fancyhead[LE]{\leftmark}
	408	""",
	409	format='latex')]
f2086c	410
CM	411	def backmatter(name, arguments, options, content, lineno,
	412	content_offset, block_text, state, state_machine):
9ec2d6	413	return [nodes.raw('', '\\backmatter\n\\setcounter{secnumdepth}{-1}\n',
CM	414	format='latex')]
f2086c	415
fd5ae9	416	def app_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
CM	417	"""custom role for :app: marker, does nothing in particular except allow
	418	:app:`Pyramid` to work (for later search and replace)."""
	419	if 'class' in options:
	420	assert 'classes' not in options
	421	options['classes'] = options['class']
	422	del options['class']
	423	return [nodes.inline(rawtext, utils.unescape(text), **options)], []
	424
	425
f2086c	426	def setup(app):
fd5ae9	427	app.add_role('app', app_role)
f2086c	428	app.add_directive('frontmatter', frontmatter, 1, (0, 0, 0))
CM	429	app.add_directive('mainmatter', mainmatter, 1, (0, 0, 0))
	430	app.add_directive('backmatter', backmatter, 1, (0, 0, 0))
be5f12	431	app.connect('autodoc-process-signature', resig)
CM	432
	433	def resig(app, what, name, obj, options, signature, return_annotation):
	434	""" Allow for preservation of ``@action_method`` decorated methods
	435	in configurator """
	436	docobj = getattr(obj, '__docobj__', None)
	437	if docobj is not None:
	438	argspec = inspect.getargspec(docobj)
	439	if argspec[0] and argspec[0][0] in ('cls', 'self'):
	440	del argspec[0][0]
	441	signature = inspect.formatargspec(*argspec)
	442	return signature, return_annotation
016a1f	443
274778	444	# turn off all line numbers in latex formatting
CM	445
	446	## from pygments.formatters import LatexFormatter
	447	## from sphinx.highlighting import PygmentsBridge
	448
	449	## class NoLinenosLatexFormatter(LatexFormatter):
	450	## def __init__(self, **options):
	451	## LatexFormatter.__init__(self, **options)
	452	## self.linenos = False
	453
	454	## PygmentsBridge.latex_formatter = NoLinenosLatexFormatter
6d47bc	455
CM	456	# -- Options for Epub output ---------------------------------------------------
	457
	458	# Bibliographic Dublin Core info.
c8c9cc	459	epub_title = 'The Pyramid Web Application Development Framework, Version 1.2'
6d47bc	460	epub_author = 'Chris McDonough'
CM	461	epub_publisher = 'Agendaless Consulting'
74c3c3	462	epub_copyright = '2008-2011'
6d47bc	463
CM	464	# The language of the text. It defaults to the language option
	465	# or en if the language is not set.
	466	epub_language = 'en'
	467
	468	# The scheme of the identifier. Typical schemes are ISBN or URL.
	469	epub_scheme = 'ISBN'
	470
	471	# The unique identifier of the text. This can be a ISBN number
	472	# or the project homepage.
5236f3	473	epub_identifier = '0615445675'
6d47bc	474
CM	475	# A unique identification for the text.
c8c9cc	476	epub_uid = 'The Pyramid Web Application Development Framework, Version 1.2'
6d47bc	477
CM	478	# HTML files that should be inserted before the pages created by sphinx.
	479	# The format is a list of tuples containing the path and title.
	480	#epub_pre_files = []
	481
	482	# HTML files shat should be inserted after the pages created by sphinx.
	483	# The format is a list of tuples containing the path and title.
	484	#epub_post_files = []
	485
	486	# A list of files that should not be packed into the epub file.
	487	#epub_exclude_files = []
	488
	489	# The depth of the table of contents in toc.ncx.
	490	epub_tocdepth = 3