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