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