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