RedHatTraining/pyramid.git

Michael Merickel

2016-05-20 b029479301c61ac78e76e0ea3f184fd3c07a3c4e

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
95d5b7	22	import pkg_resources
0bc053	23	import pylons_sphinx_themes
95d5b7	24
6cdedf	25	# skip raw nodes
CM	26	from sphinx.writers.text import TextTranslator
43889a	27	from sphinx.writers.latex import LaTeXTranslator
CM	28
6cdedf	29	from docutils import nodes
fd5ae9	30	from docutils import utils
CM	31
09f43d	32
6cdedf	33	def raw(*arg):
CM	34	raise nodes.SkipNode
	35	TextTranslator.visit_raw = raw
	36
43889a	37
CM	38	# make sure :app:`Pyramid` doesn't mess up LaTeX rendering
	39	def nothing(*arg):
	40	pass
	41	LaTeXTranslator.visit_inline = nothing
	42	LaTeXTranslator.depart_inline = nothing
	43
d22e8d	44	book = os.environ.get('BOOK')
274778	45
f70c23	46	# General configuration
CM	47	# ---------------------
	48
	49	# Add any Sphinx extension module names here, as strings. They can be extensions
	50	# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
8864e0	51	extensions = [
CM	52	'sphinx.ext.autodoc',
	53	'sphinx.ext.doctest',
	54	'repoze.sphinx.autointerface',
25f3e4	55	'sphinx.ext.viewcode',
3665ec	56	'sphinx.ext.intersphinx',
SP	57	'sphinxcontrib.programoutput',
b02947	58	'pylons_sphinx_latesturl',
8864e0	59	]
CM	60
182686	61	# Looks for objects in external projects
TL	62	intersphinx_mapping = {
3665ec	63	'colander': ('http://docs.pylonsproject.org/projects/colander/en/latest', None),
fc4740	64	'cookbook': ('http://docs.pylonsproject.org/projects/pyramid-cookbook/en/latest/', None),
b32412	65	'deform': ('http://docs.pylonsproject.org/projects/deform/en/latest', None),
fc4740	66	'jinja2': ('http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/', None),
b32412	67	'pylonswebframework': ('http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/', None),
2a65f2	68	'python': ('http://docs.python.org', None),
TL	69	'python3': ('http://docs.python.org/3', None),
b32412	70	'sqla': ('http://docs.sqlalchemy.org/en/latest', None),
bc8f11	71	'tm': ('http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/', None),
3665ec	72	'toolbar': ('http://docs.pylonsproject.org/projects/pyramid-debugtoolbar/en/latest', None),
b32412	73	'tstring': ('http://docs.pylonsproject.org/projects/translationstring/en/latest', None),
SP	74	'tutorials': ('http://docs.pylonsproject.org/projects/pyramid-tutorials/en/latest/', None),
	75	'venusian': ('http://docs.pylonsproject.org/projects/venusian/en/latest', None),
	76	'webob': ('http://docs.webob.org/en/latest', None),
	77	'webtest': ('http://webtest.pythonpaste.org/en/latest', None),
	78	'who': ('http://repozewho.readthedocs.org/en/latest', None),
	79	'zcml': ('http://docs.pylonsproject.org/projects/pyramid-zcml/en/latest', None),
	80	'zcomponent': ('http://docs.zope.org/zope.component', None),
182686	81	}
f70c23	82
b1b922	83
f70c23	84	# Add any paths that contain templates here, relative to this directory.
785d2f	85	templates_path = ['_templates']
f70c23	86
CM	87	# The suffix of source filenames.
	88	source_suffix = '.rst'
	89
	90	# The master toctree document.
	91	master_doc = 'index'
	92
	93	# General substitutions.
83fefb	94	project = 'The Pyramid Web Framework'
3604e6	95	thisyear = datetime.datetime.now().year
TL	96	copyright = '2008-%s, Agendaless Consulting' % thisyear
f70c23	97
CM	98	# The default replacements for \|version\| and \|release\|, also used in various
	99	# other places throughout the built documents.
	100	#
	101	# The short X.Y version.
95d5b7	102	version = pkg_resources.get_distribution('pyramid').version
3ee102	103
f70c23	104	# The full version, including alpha/beta/rc tags.
c0114e	105	release = version
f70c23	106
CM	107	# There are two options for replacing \|today\|: either, you set today to some
	108	# non-false value, then it is used:
	109	#today = ''
	110	# Else, today_fmt is used as the format for a strftime call.
	111	today_fmt = '%B %d, %Y'
	112
4ac753	113	# List of patterns, relative to source directory, that match files and
M	114	# directories to ignore when looking for source files.
09f43d	115	exclude_patterns = ['_themes/README.rst', ]
f70c23	116
CM	117	# If true, the current module name will be prepended to all description
	118	# unit titles (such as .. function::).
e4e3aa	119	add_module_names = False
f70c23	120
CM	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'
002c0c	125
f70c23	126	# Options for HTML output
CM	127	# -----------------------
b02947	128	pylons_sphinx_latesturl_base = (
MM	129	'http://docs.pylonsproject.org/projects/pyramid/en/latest/')
	130	pylons_sphinx_latesturl_pagename_overrides = {
	131	# map old pagename -> new pagename
	132	'whatsnew-1.0': 'index',
	133	'whatsnew-1.1': 'index',
	134	'whatsnew-1.2': 'index',
	135	'whatsnew-1.3': 'index',
	136	'whatsnew-1.4': 'index',
	137	'whatsnew-1.5': 'index',
	138	'tutorials/gae/index': 'index',
	139	'api/chameleon_text': 'api',
	140	'api/chameleon_zpt': 'api',
	141	}
f70c23	142
cc19a8	143	html_theme = 'pyramid'
0bc053	144	html_theme_path = pylons_sphinx_themes.get_html_themes_path()
d0a257	145	html_theme_options = dict(
862a26	146	github_url='https://github.com/Pylons/pyramid',
2be192	147	# on master branch true, else false
2d13f4	148	in_progress='false',
2be192	149	# on previous branches/major releases true, else false
b46a7f	150	outdated='true',
d0a257	151	)
f70c23	152
CM	153	# The name for this set of Sphinx documents. If None, it defaults to
	154	# "<project> v<release> documentation".
83fefb	155	html_title = 'The Pyramid Web Framework v%s' % release
f70c23	156
CM	157	# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
	158	# using the given strftime format.
	159	html_last_updated_fmt = '%b %d, %Y'
	160
	161	# If true, SmartyPants will be used to convert quotes and dashes to
	162	# typographically correct entities.
4aec43	163	html_use_smartypants = False # people use cutnpaste in some places
f70c23	164
CM	165	# Output file base name for HTML help builder.
71ff10	166	htmlhelp_basename = 'pyramid'
f70c23	167
CM	168	# Options for LaTeX output
	169	# ------------------------
	170
	171	# The paper size ('letter' or 'a4').
67bfd8	172	latex_paper_size = 'letter'
f70c23	173
CM	174	# The font size ('10pt', '11pt' or '12pt').
67bfd8	175	latex_font_size = '10pt'
f70c23	176
7673b0	177	latex_additional_files = ['_static/latex-note.png', '_static/latex-warning.png']
LMC	178
f70c23	179	# Grouping the document tree into LaTeX files. List of tuples
CM	180	# (source start file, target name, title, author, document class [howto/manual]).
	181	latex_documents = [
71ff10	182	('latexindex', 'pyramid.tex',
83fefb	183	'The Pyramid Web Framework',
8be78e	184	'Chris McDonough', 'manual'),
CM	185	]
f70c23	186
CM	187	# For "manual" documents, if this is true, then toplevel headings are parts,
	188	# not chapters.
67bfd8	189	latex_use_parts = True
f70c23	190
CM	191	# If false, no module index is generated.
7a3985	192	latex_use_modindex = False
125e97	193
CM	194	## Say, for a moment that you have a twoside document that needs a 3cm
	195	## inner margin to allow for binding and at least two centimetres the
	196	## rest of the way around. You've been using the a4wide package up until
	197	## now, because you like the amount of text it places on the
	198	## page. Perhaps try something like this in your preamble:
	199
	200	## \usepackage[bindingoffset=1cm,textheight=22cm,hdivide={2cm,,2cm},vdivide={,22cm,*}]{geometry}
	201
f2086c	202	## _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	203
f2086c	204	_PREAMBLE = r"""
CM	205	\usepackage[]{geometry}
	206	\geometry{bindingoffset=0.45in,textheight=7.25in,hdivide={0.5in,*,0.75in},vdivide={1in,7.25in,1in},papersize={7.5in,9.25in}}
	207	\hypersetup{
	208	colorlinks=true,
	209	linkcolor=black,
	210	citecolor=black,
	211	filecolor=black,
	212	urlcolor=black
	213	}
274778	214	\fvset{frame=single,xleftmargin=9pt,numbersep=4pt}
f2086c	215
CM	216	\pagestyle{fancy}
	217
9ec2d6	218	% header and footer styles
f2086c	219	\renewcommand{\chaptermark}[1]%
9ec2d6	220	{\markboth{\MakeUppercase{\thechapter.\ #1}}{}
CM	221	}
f2086c	222	\renewcommand{\sectionmark}[1]%
9ec2d6	223	{\markright{\MakeUppercase{\thesection.\ #1}}
CM	224	}
	225
	226	% defaults for fancy style
	227	\renewcommand{\headrulewidth}{0pt}
f2086c	228	\renewcommand{\footrulewidth}{0pt}
CM	229	\fancyhf{}
	230	\fancyfoot[C]{\thepage}
	231
9ec2d6	232	% plain style
f2086c	233	\fancypagestyle{plain}{
CM	234	\renewcommand{\headrulewidth}{0pt} % ho header line
9ec2d6	235	\renewcommand{\footrulewidth}{0pt}% no footer line
CM	236	\fancyhf{} % empty header and footer
	237	\fancyfoot[C]{\thepage}
f2086c	238	}
3a4e6f	239
9ec2d6	240	% title page styles
3a4e6f	241	\makeatletter
CM	242	\def\@subtitle{\relax}
	243	\newcommand{\subtitle}[1]{\gdef\@subtitle{#1}}
	244	\renewcommand{\maketitle}{
	245	\begin{titlepage}
	246	{\rm\Huge\@title\par}
	247	{\em\large\py@release\releaseinfo\par}
	248	\if\@subtitle\relax\else\large\@subtitle\par\fi
	249	{\large\@author\par}
	250	\end{titlepage}
	251	}
	252	\makeatother
	253
9ec2d6	254	% Redefine link and title colors
793425	255	\definecolor{TitleColor}{rgb}{0,0,0}
CM	256	\definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486}
	257	\definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388}
	258	% Redefine these colors to something not white if you want to have colored
	259	% background and border for code examples.
	260	\definecolor{VerbatimColor}{rgb}{1,1,1}
	261	\definecolor{VerbatimBorderColor}{rgb}{1,1,1}
	262
	263	\makeatletter
dc0ba7	264	\renewcommand{\py@noticestart@warning}{\py@heavybox}
CM	265	\renewcommand{\py@noticeend@warning}{\py@endheavybox}
793425	266	\renewcommand{\py@noticestart@note}{\py@heavybox}
CM	267	\renewcommand{\py@noticeend@note}{\py@endheavybox}
	268	\makeatother
	269
9ec2d6	270	% icons in note and warning boxes
dc0ba7	271	\usepackage{ifthen}
CM	272	% Keep a copy of the original notice environment
	273	\let\origbeginnotice\notice
	274	\let\origendnotice\endnotice
	275
	276	% Redefine the notice environment so we can add our own code to it
	277	\renewenvironment{notice}[2]{%
	278	\origbeginnotice{#1}{}% equivalent to original \begin{notice}{#1}{#2}
	279	% load graphics
de8c1b	280	\ifthenelse{\equal{#1}{warning}}{\includegraphics{latex-warning.png}}{}
BL	281	\ifthenelse{\equal{#1}{note}}{\includegraphics{latex-note.png}}{}
dc0ba7	282	% etc.
CM	283	}{%
	284	\origendnotice% equivalent to original \end{notice}
	285	}
	286
9ec2d6	287	% try to prevent code-block boxes from splitting across pages
44f1df	288	\sloppy
9ec2d6	289	\widowpenalty=300
CM	290	\clubpenalty=300
	291	\setlength{\parskip}{3ex plus 2ex minus 2ex}
	292
	293	% suppress page numbers on pages showing part title
	294	\makeatletter
	295	\let\sv@endpart\@endpart
	296	\def\@endpart{\thispagestyle{empty}\sv@endpart}
	297	\makeatother
	298
	299	% prevent page numbers in TOC (reset to fancy by frontmatter directive)
	300	\pagestyle{empty}
f2086c	301	"""
125e97	302
CM	303	latex_elements = {
f2086c	304	'preamble': _PREAMBLE,
09f43d	305	'wrapperclass': 'book',
GC	306	'date': '',
	307	'releasename': 'Version',
63bac4	308	'title': r'The Pyramid Web Framework',
9544d0	309	# 'pointsize':'12pt', # uncomment for 12pt version
f2086c	310	}
CM	311
9ec2d6	312	# secnumdepth counter reset to 2 causes numbering in related matter;
CM	313	# reset to -1 causes chapters to not be numbered, reset to -2 causes
	314	# parts to not be numbered.
	315
	316	#part -1
	317	#chapter 0
	318	#section 1
	319	#subsection 2
	320	#subsubsection 3
	321	#paragraph 4
	322	#subparagraph 5
09f43d	323
9ec2d6	324
f2086c	325	def frontmatter(name, arguments, options, content, lineno,
CM	326	content_offset, block_text, state, state_machine):
9ec2d6	327	return [nodes.raw(
CM	328	'',
	329	r"""
	330	\frontmatter
	331	% prevent part/chapter/section numbering
	332	\setcounter{secnumdepth}{-2}
	333	% suppress headers
	334	\pagestyle{plain}
	335	% reset page counter
	336	\setcounter{page}{1}
	337	% suppress first toc pagenum
c8b363	338	\addtocontents{toc}{\protect\thispagestyle{empty}}
9ec2d6	339	""",
CM	340	format='latex')]
09f43d	341
f2086c	342
CM	343	def mainmatter(name, arguments, options, content, lineno,
	344	content_offset, block_text, state, state_machine):
9ec2d6	345	return [nodes.raw(
CM	346	'',
	347	r"""
	348	\mainmatter
	349	% allow part/chapter/section numbering
	350	\setcounter{secnumdepth}{2}
	351	% get headers back
c8b363	352	\pagestyle{fancy}
9ec2d6	353	\fancyhf{}
CM	354	\renewcommand{\headrulewidth}{0.5pt}
	355	\renewcommand{\footrulewidth}{0pt}
	356	\fancyfoot[C]{\thepage}
	357	\fancyhead[RO]{\rightmark}
	358	\fancyhead[LE]{\leftmark}
	359	""",
	360	format='latex')]
f2086c	361
09f43d	362
f2086c	363	def backmatter(name, arguments, options, content, lineno,
CM	364	content_offset, block_text, state, state_machine):
9ec2d6	365	return [nodes.raw('', '\\backmatter\n\\setcounter{secnumdepth}{-1}\n',
CM	366	format='latex')]
09f43d	367
f2086c	368
fd5ae9	369	def app_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
CM	370	"""custom role for :app: marker, does nothing in particular except allow
	371	:app:`Pyramid` to work (for later search and replace)."""
	372	if 'class' in options:
	373	assert 'classes' not in options
	374	options['classes'] = options['class']
	375	del options['class']
	376	return [nodes.inline(rawtext, utils.unescape(text), **options)], []
	377
	378
f2086c	379	def setup(app):
fd5ae9	380	app.add_role('app', app_role)
f2086c	381	app.add_directive('frontmatter', frontmatter, 1, (0, 0, 0))
CM	382	app.add_directive('mainmatter', mainmatter, 1, (0, 0, 0))
	383	app.add_directive('backmatter', backmatter, 1, (0, 0, 0))
be5f12	384	app.connect('autodoc-process-signature', resig)
09f43d	385
be5f12	386
CM	387	def resig(app, what, name, obj, options, signature, return_annotation):
	388	""" Allow for preservation of ``@action_method`` decorated methods
	389	in configurator """
	390	docobj = getattr(obj, '__docobj__', None)
	391	if docobj is not None:
	392	argspec = inspect.getargspec(docobj)
	393	if argspec[0] and argspec[0][0] in ('cls', 'self'):
	394	del argspec[0][0]
	395	signature = inspect.formatargspec(*argspec)
	396	return signature, return_annotation
016a1f	397
274778	398	# turn off all line numbers in latex formatting
CM	399
	400	## from pygments.formatters import LatexFormatter
	401	## from sphinx.highlighting import PygmentsBridge
	402
	403	## class NoLinenosLatexFormatter(LatexFormatter):
	404	## def __init__(self, **options):
	405	## LatexFormatter.__init__(self, **options)
	406	## self.linenos = False
	407
	408	## PygmentsBridge.latex_formatter = NoLinenosLatexFormatter
6d47bc	409
CM	410	# -- Options for Epub output ---------------------------------------------------
	411
	412	# Bibliographic Dublin Core info.
83fefb	413	epub_title = 'The Pyramid Web Framework, Version %s' \
09f43d	414	% release
6d47bc	415	epub_author = 'Chris McDonough'
CM	416	epub_publisher = 'Agendaless Consulting'
3604e6	417	epub_copyright = '2008-%d' % thisyear
6d47bc	418
CM	419	# The language of the text. It defaults to the language option
	420	# or en if the language is not set.
	421	epub_language = 'en'
	422
	423	# The scheme of the identifier. Typical schemes are ISBN or URL.
	424	epub_scheme = 'ISBN'
	425
	426	# The unique identifier of the text. This can be a ISBN number
	427	# or the project homepage.
5236f3	428	epub_identifier = '0615445675'
6d47bc	429
CM	430	# A unique identification for the text.
83fefb	431	epub_uid = 'The Pyramid Web Framework, Version %s' \
09f43d	432	% release
6d47bc	433
CM	434	# A list of files that should not be packed into the epub file.
c8b363	435	epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
M	436	'_static/jquery.js', '_static/searchtools.js', '_static/underscore.js',
09f43d	437	'_static/basic.css', 'search.html', '_static/websupport.js']
c8b363	438
6d47bc	439
CM	440	# The depth of the table of contents in toc.ncx.
	441	epub_tocdepth = 3
0435cc	442
6a3eed	443	# For a list of all settings, visit http://sphinx-doc.org/config.html