RedHatTraining/pyramid.git

Michael Merickel

2017-06-27 9e3aeb68adc4a9b685a5d8c92c04ecdeba973143

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