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