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