Mercurial > kallithea
annotate docs/conf.py @ 6532:33b71a130b16
templates: properly escape inline JavaScript values
TLDR: Kallithea has issues with escaping values for use in inline JS.
Despite judicious poking of the code, no actual security vulnerabilities
have been found, just lots of corner-case bugs. This patch fixes those,
and hardens the code against actual security issues.
The long version:
To embed a Python value (typically a 'unicode' plain-text value) in a
larger file, it must be escaped in a context specific manner. Example:
>>> s = u'<script>alert("It\'s a trap!");</script>'
1) Escaped for insertion into HTML element context
>>> print cgi.escape(s)
<script>alert("It's a trap!");</script>
2) Escaped for insertion into HTML element or attribute context
>>> print h.escape(s)
<script>alert("It's a trap!");</script>
This is the default Mako escaping, as usually used by Kallithea.
3) Encoded as JSON
>>> print json.dumps(s)
"<script>alert(\"It's a trap!\");</script>"
4) Escaped for insertion into a JavaScript file
>>> print '(' + json.dumps(s) + ')'
("<script>alert(\"It's a trap!\");</script>")
The parentheses are not actually required for strings, but may be needed
to avoid syntax errors if the value is a number or dict (object).
5) Escaped for insertion into a HTML inline <script> element
>>> print h.js(s)
("\x3cscript\x3ealert(\"It's a trap!\");\x3c/script\x3e")
Here, we need to combine JS and HTML escaping, further complicated by
the fact that "<script>" tag contents can either be parsed in XHTML mode
(in which case '<', '>' and '&' must additionally be XML escaped) or
HTML mode (in which case '</script>' must be escaped, but not using HTML
escaping, which is not available in HTML "<script>" tags). Therefore,
the XML special characters (which can only occur in string literals) are
escaped using JavaScript string literal escape sequences.
(This, incidentally, is why modern web security best practices ban all
use of inline JavaScript...)
Unsurprisingly, Kallithea does not do (5) correctly. In most cases,
Kallithea might slap a pair of single quotes around the HTML escaped
Python value. A typical benign example:
$('#child_link').html('${_('No revisions')}');
This works in English, but if a localized version of the string contains
an apostrophe, the result will be broken JavaScript. In the more severe
cases, where the text is user controllable, it leaves the door open to
injections. In this example, the script inserts the string as HTML, so
Mako's implicit HTML escaping makes sense; but in many other cases, HTML
escaping is actually an error, because the value is not used by the
script in an HTML context.
The good news is that the HTML escaping thwarts attempts at XSS, since
it's impossible to inject syntactically valid JavaScript of any useful
complexity. It does allow JavaScript errors and gibberish to appear on
the page, though.
In these cases, the escaping has been fixed to use either the new 'h.js'
helper, which does JavaScript escaping (but not HTML escaping), OR the
new 'h.jshtml' helper (which does both), in those cases where it was
unclear if the value might be used (by the script) in an HTML context.
Some of these can probably be "relaxed" from h.jshtml to h.js later, but
for now, using h.jshtml fixes escaping and doesn't introduce new errors.
In a few places, Kallithea JSON encodes values in the controller, then
inserts the JSON (without any further escaping) into <script> tags. This
is also wrong, and carries actual risk of XSS vulnerabilities. However,
in all cases, security vulnerabilities were narrowly avoided due to other
filtering in Kallithea. (E.g. many special characters are banned from
appearing in usernames.) In these cases, the escaping has been fixed
and moved to the template, making it immediately visible that proper
escaping has been performed.
Mini-FAQ (frequently anticipated questions):
Q: Why do everything in one big, hard to review patch?
Q: Why add escaping in specific case FOO, it doesn't seem needed?
Because the goal here is to have "escape everywhere" as the default
policy, rather than identifying individual bugs and fixing them one
by one by adding escaping where needed. As such, this patch surely
introduces a lot of needless escaping. This is no different from
how Mako/Pylons HTML escape everything by default, even when not
needed: it's errs on the side of needless work, to prevent erring
on the side of skipping required (and security critical) work.
As for reviewability, the most important thing to notice is not where
escaping has been introduced, but any places where it might have been
missed (or where h.jshtml is needed, but h.js is used).
Q: The added escaping is kinda verbose/ugly.
That is not a question, but yes, I agree. Hopefully it'll encourage us
to move away from inline JavaScript altogether. That's a significantly
larger job, though; with luck this patch will keep us safe and secure
until such a time as we can implement the real fix.
Q: Why not use Mako filter syntax ("${val|h.js}")?
Because of long-standing Mako bug #140, preventing use of 'h' in
filters.
Q: Why not work around bug #140, or even use straight "${val|js}"?
Because Mako still applies the default h.escape filter before the
explicitly specified filters.
Q: Where do we go from here?
Longer term, we should stop doing variable expansions in script blocks,
and instead pass data to JS via e.g. data attributes, or asynchronously
using AJAX calls. Once we've done that, we can remove inline JavaScript
altogether in favor of separate script files, and set a strict Content
Security Policy explicitly blocking inline scripting, and thus also the
most common kind of cross-site scripting attack.
author | Søren Løvborg <sorenl@unity3d.com> |
---|---|
date | Tue, 28 Feb 2017 17:19:00 +0100 |
parents | 5c7b177d70ff |
children | f68db0c03a78 |
rev | line source |
---|---|
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
1 # -*- coding: utf-8 -*- |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
2 # |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
3 # Kallithea documentation build configuration file, created by |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
4 # sphinx-quickstart on Sun Oct 10 16:46:37 2010. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
5 # |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
6 # This file is execfile()d with the current directory set to its containing dir. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
7 # |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
8 # Note that not all possible configuration values are present in this |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
9 # autogenerated file. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
10 # |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
11 # All configuration values have a default; values that are commented out |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
12 # serve to show the default. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
13 |
2205
6b97fb00fa03
autogenerate year for docs/conf.py
Marcin Kuzminski <marcin@python-works.com>
parents:
850
diff
changeset
|
14 import sys |
6b97fb00fa03
autogenerate year for docs/conf.py
Marcin Kuzminski <marcin@python-works.com>
parents:
850
diff
changeset
|
15 import os |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
16 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
17 # If extensions (or modules to document with autodoc) are in another directory, |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
18 # add these directories to sys.path here. If the directory is relative to the |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
19 # documentation root, use os.path.abspath to make it absolute, like shown here. |
850
b3ec9f4af18b
Added rhodecode to sys.path at Sphinx configuration
Lukasz Balcerzak <lukasz.balcerzak@python-center.org>
parents:
587
diff
changeset
|
20 sys.path.insert(0, os.path.abspath('..')) |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
21 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
22 # -- General configuration ----------------------------------------------------- |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
23 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
24 # If your documentation needs a minimal Sphinx version, state it here. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
25 #needs_sphinx = '1.0' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
26 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
27 # Add any Sphinx extension module names here, as strings. They can be extensions |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
28 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. |
2235
b6adef467e23
changelog update + whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2205
diff
changeset
|
29 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', |
b6adef467e23
changelog update + whitespace cleanup
Marcin Kuzminski <marcin@python-works.com>
parents:
2205
diff
changeset
|
30 'sphinx.ext.intersphinx', 'sphinx.ext.todo', |
2205
6b97fb00fa03
autogenerate year for docs/conf.py
Marcin Kuzminski <marcin@python-works.com>
parents:
850
diff
changeset
|
31 'sphinx.ext.viewcode'] |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
32 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
33 # Add any paths that contain templates here, relative to this directory. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
34 templates_path = ['_templates'] |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
35 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
36 # The suffix of source filenames. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
37 source_suffix = '.rst' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
38 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
39 # The encoding of source files. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
40 #source_encoding = 'utf-8-sig' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
41 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
42 # The master toctree document. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
43 master_doc = 'index' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
44 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
45 # General information about the project. |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
46 project = u'Kallithea' |
5718 | 47 copyright = u'2010-2016 by various authors, licensed as GPLv3.' |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
48 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
49 # The version info for the project you're documenting, acts as replacement for |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
50 # |version| and |release|, also used in various other places throughout the |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
51 # built documents. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
52 # |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
53 # The short X.Y version. |
587
2ec9b6c8cace
automated, version building into sphinx
Marcin Kuzminski <marcin@python-works.com>
parents:
572
diff
changeset
|
54 root = os.path.dirname(os.path.dirname(__file__)) |
2ec9b6c8cace
automated, version building into sphinx
Marcin Kuzminski <marcin@python-works.com>
parents:
572
diff
changeset
|
55 sys.path.append(root) |
4186
7e5f8c12a3fc
First step in two-part process to rename directories to kallithea.
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
2601
diff
changeset
|
56 from kallithea import __version__ |
2601
aa90719e8520
Added troubleshooting section to docs
Marcin Kuzminski <marcin@python-works.com>
parents:
2235
diff
changeset
|
57 version = __version__ |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
58 # The full version, including alpha/beta/rc tags. |
587
2ec9b6c8cace
automated, version building into sphinx
Marcin Kuzminski <marcin@python-works.com>
parents:
572
diff
changeset
|
59 release = __version__ |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
60 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
61 # The language for content autogenerated by Sphinx. Refer to documentation |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
62 # for a list of supported languages. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
63 #language = None |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
64 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
65 # There are two options for replacing |today|: either, you set today to some |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
66 # non-false value, then it is used: |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
67 #today = '' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
68 # Else, today_fmt is used as the format for a strftime call. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
69 #today_fmt = '%B %d, %Y' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
70 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
71 # List of patterns, relative to source directory, that match files and |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
72 # directories to ignore when looking for source files. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
73 exclude_patterns = ['_build'] |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
74 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
75 # The reST default role (used for this markup: `text`) to use for all documents. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
76 #default_role = None |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
77 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
78 # If true, '()' will be appended to :func: etc. cross-reference text. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
79 #add_function_parentheses = True |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
80 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
81 # If true, the current module name will be prepended to all description |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
82 # unit titles (such as .. function::). |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
83 #add_module_names = True |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
84 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
85 # If true, sectionauthor and moduleauthor directives will be shown in the |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
86 # output. They are ignored by default. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
87 #show_authors = False |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
88 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
89 # The name of the Pygments (syntax highlighting) style to use. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
90 pygments_style = 'sphinx' |
5425
5ae8e644aa88
docs: spelling, grammar, content and typography
Søren Løvborg <sorenl@unity3d.com>
parents:
4770
diff
changeset
|
91 highlight_language = 'none' |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
92 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
93 # A list of ignored prefixes for module index sorting. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
94 #modindex_common_prefix = [] |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
95 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
96 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
97 # -- Options for HTML output --------------------------------------------------- |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
98 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
99 # The theme to use for HTML and HTML Help pages. See the documentation for |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
100 # a list of builtin themes. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
101 html_theme = 'nature' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
102 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
103 # Theme options are theme-specific and customize the look and feel of a theme |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
104 # further. For a list of options available for each theme, see the |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
105 # documentation. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
106 #html_theme_options = {} |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
107 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
108 # Add any paths that contain custom themes here, relative to this directory. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
109 html_theme_path = ['theme'] |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
110 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
111 # The name for this set of Sphinx documents. If None, it defaults to |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
112 # "<project> v<release> documentation". |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
113 #html_title = None |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
114 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
115 # A shorter title for the navigation bar. Default is the same as html_title. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
116 #html_short_title = None |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
117 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
118 # The name of an image file (relative to this directory) to place at the top |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
119 # of the sidebar. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
120 #html_logo = None |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
121 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
122 # The name of an image file (within the static path) to use as favicon of the |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
123 # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
124 # pixels large. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
125 #html_favicon = None |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
126 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
127 # Add any paths that contain custom static files (such as style sheets) here, |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
128 # relative to this directory. They are copied after the builtin static files, |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
129 # so a file named "default.css" will overwrite the builtin "default.css". |
572
a60cd29ba7e2
more docs update
Marcin Kuzminski <marcin@python-works.com>
parents:
568
diff
changeset
|
130 #html_static_path = ['_static'] |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
131 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
132 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
133 # using the given strftime format. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
134 #html_last_updated_fmt = '%b %d, %Y' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
135 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
136 # If true, SmartyPants will be used to convert quotes and dashes to |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
137 # typographically correct entities. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
138 #html_use_smartypants = True |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
139 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
140 # Custom sidebar templates, maps document names to template names. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
141 #html_sidebars = {} |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
142 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
143 # Additional templates that should be rendered to pages, maps page names to |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
144 # template names. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
145 #html_additional_pages = {} |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
146 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
147 # If false, no module index is generated. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
148 #html_domain_indices = True |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
149 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
150 # If false, no index is generated. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
151 #html_use_index = True |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
152 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
153 # If true, the index is split into individual pages for each letter. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
154 #html_split_index = False |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
155 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
156 # If true, links to the reST sources are added to the pages. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
157 #html_show_sourcelink = True |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
158 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
159 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
160 #html_show_sphinx = True |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
161 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
162 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
163 #html_show_copyright = True |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
164 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
165 # If true, an OpenSearch description file will be output, and all pages will |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
166 # contain a <link> tag referring to it. The value of this option must be the |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
167 # base URL from which the finished HTML is served. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
168 #html_use_opensearch = '' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
169 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
170 # This is the file name suffix for HTML files (e.g. ".xhtml"). |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
171 #html_file_suffix = None |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
172 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
173 # Output file base name for HTML help builder. |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
174 htmlhelp_basename = 'Kallithea-docs' |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
175 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
176 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
177 # -- Options for LaTeX output -------------------------------------------------- |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
178 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
179 # The paper size ('letter' or 'a4'). |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
180 #latex_paper_size = 'letter' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
181 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
182 # The font size ('10pt', '11pt' or '12pt'). |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
183 #latex_font_size = '10pt' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
184 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
185 # Grouping the document tree into LaTeX files. List of tuples |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
186 # (source start file, target name, title, author, documentclass [howto/manual]). |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
187 latex_documents = [ |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
188 ('index', 'Kallithea.tex', u'Kallithea Documentation', |
4249
edaeab4f4846
Update username for documents.
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4208
diff
changeset
|
189 u'Kallithea Developers', 'manual'), |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
190 ] |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
191 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
192 # The name of an image file (relative to this directory) to place at the top of |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
193 # the title page. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
194 #latex_logo = None |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
195 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
196 # For "manual" documents, if this is true, then toplevel headings are parts, |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
197 # not chapters. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
198 #latex_use_parts = False |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
199 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
200 # If true, show page references after internal links. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
201 #latex_show_pagerefs = False |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
202 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
203 # If true, show URL addresses after external links. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
204 #latex_show_urls = False |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
205 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
206 # Additional stuff for the LaTeX preamble. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
207 #latex_preamble = '' |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
208 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
209 # Documents to append as an appendix to all manuals. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
210 #latex_appendices = [] |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
211 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
212 # If false, no module index is generated. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
213 #latex_domain_indices = True |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
214 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
215 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
216 # -- Options for manual page output -------------------------------------------- |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
217 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
218 # One entry per manual page. List of tuples |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
219 # (source start file, name, description, authors, manual section). |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
220 man_pages = [ |
4192
e73a69cb98dc
Rename some strings examples and commands in documentation
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4186
diff
changeset
|
221 ('index', 'kallithea', u'Kallithea Documentation', |
4249
edaeab4f4846
Update username for documents.
Bradley M. Kuhn <bkuhn@sfconservancy.org>
parents:
4208
diff
changeset
|
222 [u'Kallithea Developers'], 1) |
568
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
223 ] |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
224 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
225 |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
226 # Example configuration for intersphinx: refer to the Python standard library. |
5f481e4e888b
updated docs, added sphinx build
Marcin Kuzminski <marcin@python-works.com>
parents:
diff
changeset
|
227 intersphinx_mapping = {'http://docs.python.org/': None} |