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