Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / jinja / 9356b7b1b4502e430c8eea289efb0d6b76aa756b / . / docs / generate.py
blob: a6dbb4e432ce863ea232d166bb56a3b415b67e1d [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
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame^]112FULL_TEMPLATE = e.from_string('''\
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]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
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame^]159PREPROC_TEMPLATE = e.from_string('''\
160<!-- TITLE -->{{ title }}<!-- ENDTITLE -->
161<!-- TOC -->{% for key, value in toc %}<li><a href="{{
162 key }}">{{ value }}</a></li>{% endfor %}<!-- ENDTOC -->
163<!-- BODY -->{{ body }}<!-- ENDBODY -->\
164''')
165
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]166def pygments_directive(name, arguments, options, content, lineno,
167 content_offset, block_text, state, state_machine):
168 try:
169 lexer = get_lexer_by_name(arguments[0])
170 except ValueError:
171 # no lexer found
172 lexer = get_lexer_by_name('text')
173 parsed = highlight(u'\n'.join(content), lexer, PYGMENTS_FORMATTER)
174 return [nodes.raw('', parsed, format="html")]
175pygments_directive.arguments = (1, 0, 1)
176pygments_directive.content = 1
177directives.register_directive('sourcecode', pygments_directive)
178
179
180def create_translator(link_style):
181 class Translator(html4css1.HTMLTranslator):
182 def visit_reference(self, node):
183 refuri = node.get('refuri')
184 if refuri is not None and '/' not in refuri and refuri.endswith('.txt'):
185 node['refuri'] = link_style(refuri[:-4])
186 html4css1.HTMLTranslator.visit_reference(self, node)
187 return Translator
188
189
190class DocumentationWriter(html4css1.Writer):
191
192 def __init__(self, link_style):
193 html4css1.Writer.__init__(self)
194 self.translator_class = create_translator(link_style)
195
196 def translate(self):
197 html4css1.Writer.translate(self)
198 # generate table of contents
199 contents = self.build_contents(self.document)
200 contents_doc = self.document.copy()
201 contents_doc.children = contents
202 contents_visitor = self.translator_class(contents_doc)
203 contents_doc.walkabout(contents_visitor)
204 self.parts['toc'] = self._generated_toc
205
206 def build_contents(self, node, level=0):
207 sections = []
208 i = len(node) - 1
209 while i >= 0 and isinstance(node[i], nodes.section):
210 sections.append(node[i])
211 i -= 1
212 sections.reverse()
213 toc = []
214 for section in sections:
215 try:
216 reference = nodes.reference('', '', refid=section['ids'][0], *section[0])
217 except IndexError:
218 continue
219 ref_id = reference['refid']
220 text = escape(reference.astext().encode('utf-8'))
221 toc.append((ref_id, text))
222
223 self._generated_toc = [('#%s' % href, caption) for href, caption in toc]
224 # no further processing
225 return []
226
227
228def generate_documentation(data, link_style):
229 writer = DocumentationWriter(link_style)
230 data = data.replace('[[list_of_filters]]', LIST_OF_FILTERS)\
231 .replace('[[list_of_tests]]', LIST_OF_TESTS)\
232 .replace('[[list_of_loaders]]', LIST_OF_LOADERS)
233 parts = publish_parts(
234 data,
235 writer=writer,
236 settings_overrides={
237 'initial_header_level': 3,
238 'field_name_limit': 50,
239 }
240 )
241 return {
242 'title': parts['title'].encode('utf-8'),
243 'body': parts['body'].encode('utf-8'),
244 'toc': parts['toc']
245 }
246
247
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame^]248def handle_file(filename, fp, dst, preproc):
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]249 now = datetime.now()
250 title = os.path.basename(filename)[:-4]
251 content = fp.read()
252 parts = generate_documentation(content, (lambda x: './%s.html' % x))
253 result = file(os.path.join(dst, title + '.html'), 'w')
254 c = dict(parts)
255 c['style'] = PYGMENTS_FORMATTER.get_style_defs('.syntax')
256 c['generation_date'] = now
257 c['file_id'] = title
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame^]258 if preproc:
259 tmpl = PREPROC_TEMPLATE
260 else:
261 tmpl = FULL_TEMPLATE
262 result.write(tmpl.render(c).encode('utf-8'))
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]263 result.close()
264
265
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame^]266def run(dst, preproc, sources=(), handle_file=handle_file):
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]267 path = os.path.abspath(os.path.join(os.path.dirname(__file__), 'src'))
268 if not sources:
269 sources = [os.path.join(path, fn) for fn in os.listdir(path)]
270 for fn in sources:
271 if not os.path.isfile(fn):
272 continue
273 print 'Processing %s' % fn
274 f = open(fn)
275 try:
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame^]276 handle_file(fn, f, dst, preproc)
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]277 finally:
278 f.close()
279
280
Armin Ronacher9356b7b2007-03-13 22:29:01 +0100[diff] [blame^]281def main(dst='build/', preproc=False, *sources):
282 run(os.path.realpath(dst), str(preproc).lower() == 'true', sources)
Armin Ronacher37a88512007-03-02 20:42:18 +0100[diff] [blame]283
284
285if __name__ == '__main__':
286 main(*sys.argv[1:])