Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / jinja / 215809146c04657188b3617359e330b4fbd2bb12 / . / docs / generate.py
blob: 8acf5b7626f21e0397f291ade8338803af9438f6 [file] [log] [blame]
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]1#!/usr/bin/env python
2# -*- coding: utf-8 -*-
3"""
4 Generate Jinja Documentation
5 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6
7 Generates a bunch of html files containing the documentation.
8
9 :copyright: 2006-2007 by Armin Ronacher, Georg Brandl.
10 :license: BSD, see LICENSE for more details.
11"""
12import os
13import sys
14sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
15import re
16import inspect
17from datetime import datetime
18from cgi import escape
19
20from docutils import nodes
21from docutils.parsers.rst import directives
22from docutils.core import publish_parts
23from docutils.writers import html4css1
24
25from jinja import Environment
26
27from pygments import highlight
28from pygments.lexers import get_lexer_by_name
29from pygments.formatters import HtmlFormatter
30
31def generate_list_of_filters():
32 from jinja.filters import FILTERS
33 result = []
34
35 filters = {}
36 for name, f in FILTERS.iteritems():
37 if not f in filters:
38 filters[f] = ([name], inspect.getdoc(f))
39 else:
40 filters[f][0].append(name)
41 for names, _ in filters.itervalues():
42 names.sort(key=lambda x: -len(x))
43
44 for names, doc in sorted(filters.values(), key=lambda x: x[0][0].lower()):
45 name = names[0]
46 if len(names) > 1:
47 aliases = '\n\n :Aliases: %s\n' % ', '.join(names[1:])
48 else:
49 aliases = ''
50
51 doclines = []
52 for line in doc.splitlines():
53 doclines.append(' ' + line)
54 doc = '\n'.join(doclines)
55 result.append('`%s`\n%s%s' % (name, doc, aliases))
56
57 return '\n'.join(result)
58
59def generate_list_of_tests():
60 from jinja.tests import TESTS
61 result = []
62
63 tests = {}
64 for name, f in TESTS.iteritems():
65 if not f in tests:
66 tests[f] = ([name], inspect.getdoc(f))
67 else:
68 tests[f][0].append(name)
69 for names, _ in tests.itervalues():
70 names.sort(key=lambda x: -len(x))
71
72 for names, doc in sorted(tests.values(), key=lambda x: x[0][0].lower()):
73 name = names[0]
74 if len(names) > 1:
75 aliases = '\n\n :Aliases: %s\n' % ', '.join(names[1:])
76 else:
77 aliases = ''
78
79 doclines = []
80 for line in doc.splitlines():
81 doclines.append(' ' + line)
82 doc = '\n'.join(doclines)
83 result.append('`%s`\n%s%s' % (name, doc, aliases))
84
85 return '\n'.join(result)
86
87def generate_list_of_loaders():
88 from jinja import loaders as loader_module
89
90 result = []
91 loaders = []
92 for item in loader_module.__all__:
93 loaders.append(getattr(loader_module, item))
94 loaders.sort(key=lambda x: x.__name__.lower())
95
96 for loader in loaders:
97 doclines = []
98 for line in inspect.getdoc(loader).splitlines():
99 doclines.append(' ' + line)
100 result.append('`%s`\n%s' % (loader.__name__, '\n'.join(doclines)))
101
102 return '\n\n'.join(result)
103
Armin Ronacher5a8e4972007-04-05 11:21:38 +0200[diff] [blame]104def generate_environment_doc():
105 from jinja.environment import Environment
106 return '%s\n\n%s' % (
107 inspect.getdoc(Environment),
108 inspect.getdoc(Environment.__init__)
109 )
110
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]111e = Environment()
112
113PYGMENTS_FORMATTER = HtmlFormatter(style='pastie', cssclass='syntax')
114
115LIST_OF_FILTERS = generate_list_of_filters()
116LIST_OF_TESTS = generate_list_of_tests()
117LIST_OF_LOADERS = generate_list_of_loaders()
Armin Ronacher5a8e4972007-04-05 11:21:38 +0200[diff] [blame]118ENVIRONMENT_DOC = generate_environment_doc()
Armin Ronachera38b3122007-04-15 00:49:13 +0200[diff] [blame]119CHANGELOG = file(os.path.join(os.path.dirname(__file__), os.pardir, 'CHANGES'))\
120 .read().decode('utf-8')
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]121
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]122FULL_TEMPLATE = e.from_string('''\
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]123<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
124 "http://www.w3.org/TR/html4/strict.dtd">
125<html>
126<head>
127 <title>{{ title }} &mdash; Jinja Documentation</title>
128 <meta http-equiv="content-type" content="text/html; charset=utf-8">
129 <link rel="stylesheet" href="style.css" type="text/css">
130 <style type="text/css">
131 {{ style|e }}
132 </style>
133</head>
134<body>
135 <div id="content">
136 {% if file_id == 'index' %}
137 <div id="jinjalogo"></div>
138 <h2 class="subheading plain">{{ title }}</h2>
139 {% else %}
140 <h1 class="heading"><span>Jinja</span></h1>
141 <h2 class="subheading">{{ title }}</h2>
142 {% endif %}
143 {% if file_id != 'index' or toc %}
144 <div id="toc">
145 <h2>Navigation</h2>
146 <ul>
147 <li><a href="index.html">back to index</a></li>
148 </ul>
149 {% if toc %}
150 <h2>Contents</h2>
151 <ul class="contents">
152 {% for key, value in toc %}
153 <li><a href="{{ key }}">{{ value }}</a></li>
154 {% endfor %}
155 </ul>
156 {% endif %}
157 </div>
158 {% endif %}
159 <div id="contentwrapper">
160 {{ body }}
161 </div>
162 </div>
163</body>
164<!-- generated on: {{ generation_date }}
165 file id: {{ file_id }} -->
166</html>\
167''')
168
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]169PREPROC_TEMPLATE = e.from_string('''\
170<!-- TITLE -->{{ title }}<!-- ENDTITLE -->
171<!-- TOC -->{% for key, value in toc %}<li><a href="{{
172 key }}">{{ value }}</a></li>{% endfor %}<!-- ENDTOC -->
173<!-- BODY -->{{ body }}<!-- ENDBODY -->\
174''')
175
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]176def pygments_directive(name, arguments, options, content, lineno,
177 content_offset, block_text, state, state_machine):
178 try:
179 lexer = get_lexer_by_name(arguments[0])
180 except ValueError:
181 # no lexer found
182 lexer = get_lexer_by_name('text')
183 parsed = highlight(u'\n'.join(content), lexer, PYGMENTS_FORMATTER)
184 return [nodes.raw('', parsed, format="html")]
185pygments_directive.arguments = (1, 0, 1)
186pygments_directive.content = 1
187directives.register_directive('sourcecode', pygments_directive)
188
189
190def create_translator(link_style):
191 class Translator(html4css1.HTMLTranslator):
192 def visit_reference(self, node):
193 refuri = node.get('refuri')
194 if refuri is not None and '/' not in refuri and refuri.endswith('.txt'):
195 node['refuri'] = link_style(refuri[:-4])
196 html4css1.HTMLTranslator.visit_reference(self, node)
197 return Translator
198
199
200class DocumentationWriter(html4css1.Writer):
201
202 def __init__(self, link_style):
203 html4css1.Writer.__init__(self)
204 self.translator_class = create_translator(link_style)
205
206 def translate(self):
207 html4css1.Writer.translate(self)
208 # generate table of contents
209 contents = self.build_contents(self.document)
210 contents_doc = self.document.copy()
211 contents_doc.children = contents
212 contents_visitor = self.translator_class(contents_doc)
213 contents_doc.walkabout(contents_visitor)
214 self.parts['toc'] = self._generated_toc
215
216 def build_contents(self, node, level=0):
217 sections = []
218 i = len(node) - 1
219 while i >= 0 and isinstance(node[i], nodes.section):
220 sections.append(node[i])
221 i -= 1
222 sections.reverse()
223 toc = []
224 for section in sections:
225 try:
226 reference = nodes.reference('', '', refid=section['ids'][0], *section[0])
227 except IndexError:
228 continue
229 ref_id = reference['refid']
230 text = escape(reference.astext().encode('utf-8'))
231 toc.append((ref_id, text))
232
233 self._generated_toc = [('#%s' % href, caption) for href, caption in toc]
234 # no further processing
235 return []
236
237
238def generate_documentation(data, link_style):
239 writer = DocumentationWriter(link_style)
240 data = data.replace('[[list_of_filters]]', LIST_OF_FILTERS)\
241 .replace('[[list_of_tests]]', LIST_OF_TESTS)\
Armin Ronacher5a8e4972007-04-05 11:21:38 +0200[diff] [blame]242 .replace('[[list_of_loaders]]', LIST_OF_LOADERS)\
Armin Ronachera38b3122007-04-15 00:49:13 +0200[diff] [blame]243 .replace('[[environment_doc]]', ENVIRONMENT_DOC)\
244 .replace('[[changelog]]', CHANGELOG)
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]245 parts = publish_parts(
246 data,
247 writer=writer,
248 settings_overrides={
Armin Ronacher21580912007-04-17 17:13:10 +0200[diff] [blame^]249 'initial_header_level': 2,
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]250 'field_name_limit': 50,
251 }
252 )
253 return {
254 'title': parts['title'].encode('utf-8'),
255 'body': parts['body'].encode('utf-8'),
256 'toc': parts['toc']
257 }
258
259
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]260def handle_file(filename, fp, dst, preproc):
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]261 now = datetime.now()
262 title = os.path.basename(filename)[:-4]
263 content = fp.read()
Armin Ronacher1f1823c2007-04-05 19:15:11 +0200[diff] [blame]264 suffix = not preproc and '.html' or ''
265 parts = generate_documentation(content, (lambda x: './%s%s' % (x, suffix)))
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]266 result = file(os.path.join(dst, title + '.html'), 'w')
267 c = dict(parts)
268 c['style'] = PYGMENTS_FORMATTER.get_style_defs('.syntax')
269 c['generation_date'] = now
270 c['file_id'] = title
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]271 if preproc:
272 tmpl = PREPROC_TEMPLATE
273 else:
274 tmpl = FULL_TEMPLATE
275 result.write(tmpl.render(c).encode('utf-8'))
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]276 result.close()
277
278
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]279def run(dst, preproc, sources=(), handle_file=handle_file):
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]280 path = os.path.abspath(os.path.join(os.path.dirname(__file__), 'src'))
281 if not sources:
282 sources = [os.path.join(path, fn) for fn in os.listdir(path)]
283 for fn in sources:
284 if not os.path.isfile(fn):
285 continue
286 print 'Processing %s' % fn
287 f = open(fn)
288 try:
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]289 handle_file(fn, f, dst, preproc)
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]290 finally:
291 f.close()
292
293
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]294def main(dst='build/', preproc=False, *sources):
295 run(os.path.realpath(dst), str(preproc).lower() == 'true', sources)
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]296
297
298if __name__ == '__main__':
299 main(*sys.argv[1:])