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