RedHatTraining/pyramid.git

Chris McDonough

2011-11-21 4a572dc008e776b08e0c4509b33282a64dcce0f2

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