RedHatTraining/pyramid.git

Chris McDonough

2013-08-30 9c2424ac80160540748607d12839f99b4af93add

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