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