Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 194 lines (165 sloc) 6.895 kB
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
1 # -*- coding: utf-8 -*-
2 """
3 Jinja Documentation Extensions
4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5
6 Support for automatically documenting filters and tests.
7
8 :copyright: Copyright 2008 by Armin Ronacher.
9 :license: BSD.
10 """
9d472df @mitsuhiko added style for html documentation
authored
11 import os
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
12 import re
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
13 import inspect
9d472df @mitsuhiko added style for html documentation
authored
14 import jinja2
15 from itertools import islice
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
16 from types import BuiltinFunctionType
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
17 from docutils import nodes
18 from docutils.statemachine import ViewList
19 from sphinx.ext.autodoc import prepare_docstring
9d472df @mitsuhiko added style for html documentation
authored
20 from sphinx.application import TemplateBridge
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
21 from pygments.style import Style
22 from pygments.token import Keyword, Name, Comment, String, Error, \
23 Number, Operator, Generic
9d472df @mitsuhiko added style for html documentation
authored
24 from jinja2 import Environment, FileSystemLoader
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
25
26
023b5e9 @mitsuhiko First extension interface documentation and updates in that interface
authored
27 def parse_rst(state, content_offset, doc):
28 node = nodes.section()
29 # hack around title style bookkeeping
30 surrounding_title_styles = state.memo.title_styles
31 surrounding_section_level = state.memo.section_level
32 state.memo.title_styles = []
33 state.memo.section_level = 0
34 state.nested_parse(doc, content_offset, node, match_titles=1)
35 state.memo.title_styles = surrounding_title_styles
36 state.memo.section_level = surrounding_section_level
37 return node.children
38
39
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
40 class JinjaStyle(Style):
41 title = 'Jinja Style'
42 default_style = ""
43 styles = {
44 Comment: 'italic #aaaaaa',
45 Comment.Preproc: 'noitalic #B11414',
46 Comment.Special: 'italic #505050',
47
48 Keyword: 'bold #B80000',
49 Keyword.Type: '#808080',
50
5411ce7 @mitsuhiko even more tests, fixed severe bug with autoescaping.
authored
51 Operator.Word: 'bold #B80000',
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
52
53 Name.Builtin: '#333333',
54 Name.Function: '#333333',
55 Name.Class: 'bold #333333',
56 Name.Namespace: 'bold #333333',
57 Name.Entity: 'bold #363636',
58 Name.Attribute: '#686868',
59 Name.Tag: 'bold #686868',
60 Name.Decorator: '#686868',
61
7259c76 @mitsuhiko moved caching from loaders to environment and added environment overlays
authored
62 String: '#AA891C',
b2a36aa @mitsuhiko updated jinja docs
authored
63 Number: '#444444',
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
64
65 Generic.Heading: 'bold #000080',
66 Generic.Subheading: 'bold #800080',
67 Generic.Deleted: '#aa0000',
68 Generic.Inserted: '#00aa00',
69 Generic.Error: '#aa0000',
70 Generic.Emph: 'italic',
71 Generic.Strong: 'bold',
72 Generic.Prompt: '#555555',
73 Generic.Output: '#888888',
74 Generic.Traceback: '#aa0000',
75
76 Error: '#F00 bg:#FAA'
77 }
78
9d472df @mitsuhiko added style for html documentation
authored
79
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
80 _sig_re = re.compile(r'^[a-zA-Z_][a-zA-Z0-9_]*(\(.*?\))')
81
82
83 def format_function(name, aliases, func):
84 lines = inspect.getdoc(func).splitlines()
85 signature = '()'
86 if isinstance(func, BuiltinFunctionType):
87 match = _sig_re.match(lines[0])
88 if match is not None:
89 del lines[:1 + bool(lines and not lines[0])]
90 signature = match.group(1)
91 else:
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
92 try:
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
93 argspec = inspect.getargspec(func)
94 if getattr(func, 'environmentfilter', False) or \
d464d08 @mitsuhiko Fixed a bug in the documentation tool
authored
95 getattr(func, 'contextfilter', False) or \
96 getattr(func, 'evalcontextfilter', False):
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
97 del argspec[0][0]
98 signature = inspect.formatargspec(*argspec)
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
99 except:
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
100 pass
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
101 result = ['.. function:: %s%s' % (name, signature), '']
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
102 result.extend(' ' + line for line in lines)
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
103 if aliases:
104 result.extend(('', ' :aliases: %s' % ', '.join(
105 '``%s``' % x for x in sorted(aliases))))
106 return result
107
108
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
109 def dump_functions(mapping):
110 def directive(dirname, arguments, options, content, lineno,
111 content_offset, block_text, state, state_machine):
112 reverse_mapping = {}
113 for name, func in mapping.iteritems():
114 reverse_mapping.setdefault(func, []).append(name)
115 filters = []
116 for func, names in reverse_mapping.iteritems():
117 aliases = sorted(names, key=lambda x: len(x))
118 name = aliases.pop()
119 filters.append((name, aliases, func))
120 filters.sort()
121
122 result = ViewList()
123 for name, aliases, func in filters:
124 for item in format_function(name, aliases, func):
125 result.append(item, '<jinjaext>')
126
127 node = nodes.paragraph()
128 state.nested_parse(result, content_offset, node)
129 return node.children
130 return directive
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
131
132
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
133 from jinja2.defaults import DEFAULT_FILTERS, DEFAULT_TESTS
134 jinja_filters = dump_functions(DEFAULT_FILTERS)
135 jinja_tests = dump_functions(DEFAULT_TESTS)
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
136
137
023b5e9 @mitsuhiko First extension interface documentation and updates in that interface
authored
138 def jinja_nodes(dirname, arguments, options, content, lineno,
139 content_offset, block_text, state, state_machine):
140 from jinja2.nodes import Node
141 doc = ViewList()
142 def walk(node, indent):
143 p = ' ' * indent
144 sig = ', '.join(node.fields)
145 doc.append(p + '.. autoclass:: %s(%s)' % (node.__name__, sig), '')
146 if node.abstract:
147 members = []
148 for key, name in node.__dict__.iteritems():
69e12db @mitsuhiko improved variable exporting, added TODO file
authored
149 if not key.startswith('_') and \
150 not hasattr(node.__base__, key) and callable(name):
023b5e9 @mitsuhiko First extension interface documentation and updates in that interface
authored
151 members.append(key)
152 if members:
153 members.sort()
154 doc.append('%s :members: %s' % (p, ', '.join(members)), '')
69e12db @mitsuhiko improved variable exporting, added TODO file
authored
155 if node.__base__ != object:
023b5e9 @mitsuhiko First extension interface documentation and updates in that interface
authored
156 doc.append('', '')
69e12db @mitsuhiko improved variable exporting, added TODO file
authored
157 doc.append('%s :Node type: :class:`%s`' %
158 (p, node.__base__.__name__), '')
023b5e9 @mitsuhiko First extension interface documentation and updates in that interface
authored
159 doc.append('', '')
160 children = node.__subclasses__()
161 children.sort(key=lambda x: x.__name__.lower())
162 for child in children:
163 walk(child, indent)
164 walk(Node, 0)
165 return parse_rst(state, content_offset, doc)
166
167
3ef2043 @mitsuhiko updated documentation
authored
168 def inject_toc(app, doctree, docname):
169 titleiter = iter(doctree.traverse(nodes.title))
170 try:
171 # skip first title, we are not interested in that one
172 titleiter.next()
173 title = titleiter.next()
174 # and check if there is at least another title
175 titleiter.next()
176 except StopIteration:
177 return
178 tocnode = nodes.section('')
179 tocnode['classes'].append('toc')
180 toctitle = nodes.section('')
181 toctitle['classes'].append('toctitle')
182 toctitle.append(nodes.title(text='Table Of Contents'))
183 tocnode.append(toctitle)
184 tocnode += doctree.document.settings.env.get_toc_for(docname)[0][1]
185 title.parent.insert(title.parent.children.index(title), tocnode)
186
187
3c8b7ad @mitsuhiko first version of the jinja2 docs
authored
188 def setup(app):
157531b @mitsuhiko more docs and fixed bug in parser that assigned lineno for ExprStmt w…
authored
189 app.add_directive('jinjafilters', jinja_filters, 0, (0, 0, 0))
190 app.add_directive('jinjatests', jinja_tests, 0, (0, 0, 0))
023b5e9 @mitsuhiko First extension interface documentation and updates in that interface
authored
191 app.add_directive('jinjanodes', jinja_nodes, 0, (0, 0, 0))
3ef2043 @mitsuhiko updated documentation
authored
192 # uncomment for inline toc. links are broken unfortunately
193 ##app.connect('doctree-resolved', inject_toc)
Something went wrong with that request. Please try again.