Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / jinja / 5a8e49723a7aa1f2ee740fc20f2048a1e5a05fcb / . / docs / generate.py
blob: 9ae42f4a98b1c21b540f2f6e35a1ebb968ebd1c5 [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 Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]119
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]120FULL_TEMPLATE = e.from_string('''\
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]121<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
122 "http://www.w3.org/TR/html4/strict.dtd">
123<html>
124<head>
125 <title>{{ title }} &mdash; Jinja Documentation</title>
126 <meta http-equiv="content-type" content="text/html; charset=utf-8">
127 <link rel="stylesheet" href="style.css" type="text/css">
128 <style type="text/css">
129 {{ style|e }}
130 </style>
131</head>
132<body>
133 <div id="content">
134 {% if file_id == 'index' %}
135 <div id="jinjalogo"></div>
136 <h2 class="subheading plain">{{ title }}</h2>
137 {% else %}
138 <h1 class="heading"><span>Jinja</span></h1>
139 <h2 class="subheading">{{ title }}</h2>
140 {% endif %}
141 {% if file_id != 'index' or toc %}
142 <div id="toc">
143 <h2>Navigation</h2>
144 <ul>
145 <li><a href="index.html">back to index</a></li>
146 </ul>
147 {% if toc %}
148 <h2>Contents</h2>
149 <ul class="contents">
150 {% for key, value in toc %}
151 <li><a href="{{ key }}">{{ value }}</a></li>
152 {% endfor %}
153 </ul>
154 {% endif %}
155 </div>
156 {% endif %}
157 <div id="contentwrapper">
158 {{ body }}
159 </div>
160 </div>
161</body>
162<!-- generated on: {{ generation_date }}
163 file id: {{ file_id }} -->
164</html>\
165''')
166
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]167PREPROC_TEMPLATE = e.from_string('''\
168<!-- TITLE -->{{ title }}<!-- ENDTITLE -->
169<!-- TOC -->{% for key, value in toc %}<li><a href="{{
170 key }}">{{ value }}</a></li>{% endfor %}<!-- ENDTOC -->
171<!-- BODY -->{{ body }}<!-- ENDBODY -->\
172''')
173
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]174def pygments_directive(name, arguments, options, content, lineno,
175 content_offset, block_text, state, state_machine):
176 try:
177 lexer = get_lexer_by_name(arguments[0])
178 except ValueError:
179 # no lexer found
180 lexer = get_lexer_by_name('text')
181 parsed = highlight(u'\n'.join(content), lexer, PYGMENTS_FORMATTER)
182 return [nodes.raw('', parsed, format="html")]
183pygments_directive.arguments = (1, 0, 1)
184pygments_directive.content = 1
185directives.register_directive('sourcecode', pygments_directive)
186
187
188def create_translator(link_style):
189 class Translator(html4css1.HTMLTranslator):
190 def visit_reference(self, node):
191 refuri = node.get('refuri')
192 if refuri is not None and '/' not in refuri and refuri.endswith('.txt'):
193 node['refuri'] = link_style(refuri[:-4])
194 html4css1.HTMLTranslator.visit_reference(self, node)
195 return Translator
196
197
198class DocumentationWriter(html4css1.Writer):
199
200 def __init__(self, link_style):
201 html4css1.Writer.__init__(self)
202 self.translator_class = create_translator(link_style)
203
204 def translate(self):
205 html4css1.Writer.translate(self)
206 # generate table of contents
207 contents = self.build_contents(self.document)
208 contents_doc = self.document.copy()
209 contents_doc.children = contents
210 contents_visitor = self.translator_class(contents_doc)
211 contents_doc.walkabout(contents_visitor)
212 self.parts['toc'] = self._generated_toc
213
214 def build_contents(self, node, level=0):
215 sections = []
216 i = len(node) - 1
217 while i >= 0 and isinstance(node[i], nodes.section):
218 sections.append(node[i])
219 i -= 1
220 sections.reverse()
221 toc = []
222 for section in sections:
223 try:
224 reference = nodes.reference('', '', refid=section['ids'][0], *section[0])
225 except IndexError:
226 continue
227 ref_id = reference['refid']
228 text = escape(reference.astext().encode('utf-8'))
229 toc.append((ref_id, text))
230
231 self._generated_toc = [('#%s' % href, caption) for href, caption in toc]
232 # no further processing
233 return []
234
235
236def generate_documentation(data, link_style):
237 writer = DocumentationWriter(link_style)
238 data = data.replace('[[list_of_filters]]', LIST_OF_FILTERS)\
239 .replace('[[list_of_tests]]', LIST_OF_TESTS)\
Armin Ronacher5a8e4972007-04-05 11:21:38 +0200[diff] [blame^]240 .replace('[[list_of_loaders]]', LIST_OF_LOADERS)\
241 .replace('[[environment_doc]]', ENVIRONMENT_DOC)
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]242 parts = publish_parts(
243 data,
244 writer=writer,
245 settings_overrides={
246 'initial_header_level': 3,
247 'field_name_limit': 50,
248 }
249 )
250 return {
251 'title': parts['title'].encode('utf-8'),
252 'body': parts['body'].encode('utf-8'),
253 'toc': parts['toc']
254 }
255
256
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]257def handle_file(filename, fp, dst, preproc):
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]258 now = datetime.now()
259 title = os.path.basename(filename)[:-4]
260 content = fp.read()
261 parts = generate_documentation(content, (lambda x: './%s.html' % x))
262 result = file(os.path.join(dst, title + '.html'), 'w')
263 c = dict(parts)
264 c['style'] = PYGMENTS_FORMATTER.get_style_defs('.syntax')
265 c['generation_date'] = now
266 c['file_id'] = title
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]267 if preproc:
268 tmpl = PREPROC_TEMPLATE
269 else:
270 tmpl = FULL_TEMPLATE
271 result.write(tmpl.render(c).encode('utf-8'))
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]272 result.close()
273
274
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]275def run(dst, preproc, sources=(), handle_file=handle_file):
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]276 path = os.path.abspath(os.path.join(os.path.dirname(__file__), 'src'))
277 if not sources:
278 sources = [os.path.join(path, fn) for fn in os.listdir(path)]
279 for fn in sources:
280 if not os.path.isfile(fn):
281 continue
282 print 'Processing %s' % fn
283 f = open(fn)
284 try:
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]285 handle_file(fn, f, dst, preproc)
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]286 finally:
287 f.close()
288
289
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame]290def main(dst='build/', preproc=False, *sources):
291 run(os.path.realpath(dst), str(preproc).lower() == 'true', sources)
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]292
293
294if __name__ == '__main__':
295 main(*sys.argv[1:])