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