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