Edited the READMEs and documentation to be cleaner and more consistent.
[philo.git] / docs / _ext / djangodocs.py
1 """
2 Sphinx plugins for Django documentation.
3 """
4 import os
5 import re
6
7 from docutils import nodes, transforms
8 try:
9     import json
10 except ImportError:
11     try:
12         import simplejson as json
13     except ImportError:
14         try:
15             from django.utils import simplejson as json
16         except ImportError:
17             json = None
18
19 from sphinx import addnodes, roles
20 from sphinx.builders.html import StandaloneHTMLBuilder
21 from sphinx.writers.html import SmartyPantsHTMLTranslator
22 from sphinx.util.console import bold
23 from sphinx.util.compat import Directive
24
25 # RE for option descriptions without a '--' prefix
26 simple_option_desc_re = re.compile(
27     r'([-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)')
28
29 def setup(app):
30     app.add_crossref_type(
31         directivename = "setting",
32         rolename      = "setting",
33         indextemplate = "pair: %s; setting",
34     )
35     #app.add_crossref_type(
36     #    directivename = "templatetag",
37     #    rolename      = "ttag",
38     #    indextemplate = "pair: %s; template tag"
39     #)
40     #app.add_crossref_type(
41     #    directivename = "templatefilter",
42     #    rolename      = "tfilter",
43     #    indextemplate = "pair: %s; template filter"
44     #)
45     app.add_crossref_type(
46         directivename = "fieldlookup",
47         rolename      = "lookup",
48         indextemplate = "pair: %s; field lookup type",
49     )
50     app.add_description_unit(
51         directivename = "django-admin",
52         rolename      = "djadmin",
53         indextemplate = "pair: %s; django-admin command",
54         parse_node    = parse_django_admin_node,
55     )
56     app.add_description_unit(
57         directivename = "django-admin-option",
58         rolename      = "djadminopt",
59         indextemplate = "pair: %s; django-admin command-line option",
60         parse_node    = parse_django_adminopt_node,
61     )
62     app.add_config_value('django_next_version', '0.0', True)
63     app.add_directive('versionadded', VersionDirective)
64     app.add_directive('versionchanged', VersionDirective)
65     app.add_transform(SuppressBlockquotes)
66     app.add_builder(DjangoStandaloneHTMLBuilder)
67
68
69 class VersionDirective(Directive):
70     has_content = True
71     required_arguments = 1
72     optional_arguments = 1
73     final_argument_whitespace = True
74     option_spec = {}
75
76     def run(self):
77         env = self.state.document.settings.env
78         arg0 = self.arguments[0]
79         is_nextversion = env.config.django_next_version == arg0
80         ret = []
81         node = addnodes.versionmodified()
82         ret.append(node)
83         if not is_nextversion:
84             if len(self.arguments) == 1:
85                 linktext = 'Please, see the release notes </releases/%s>' % (arg0)
86                 xrefs = roles.XRefRole()('doc', linktext, linktext, self.lineno, self.state)
87                 node.extend(xrefs[0])
88             node['version'] = arg0
89         else:
90             node['version'] = "Development version"
91         node['type'] = self.name
92         if len(self.arguments) == 2:
93             inodes, messages = self.state.inline_text(self.arguments[1], self.lineno+1)
94             node.extend(inodes)
95             if self.content:
96                 self.state.nested_parse(self.content, self.content_offset, node)
97             ret = ret + messages
98         env.note_versionchange(node['type'], node['version'], node, self.lineno)
99         return ret
100
101
102 class SuppressBlockquotes(transforms.Transform):
103     """
104     Remove the default blockquotes that encase indented list, tables, etc.
105     """
106     default_priority = 300
107
108     suppress_blockquote_child_nodes = (
109         nodes.bullet_list,
110         nodes.enumerated_list,
111         nodes.definition_list,
112         nodes.literal_block,
113         nodes.doctest_block,
114         nodes.line_block,
115         nodes.table
116     )
117
118     def apply(self):
119         for node in self.document.traverse(nodes.block_quote):
120             if len(node.children) == 1 and isinstance(node.children[0], self.suppress_blockquote_child_nodes):
121                 node.replace_self(node.children[0])
122
123 class DjangoHTMLTranslator(SmartyPantsHTMLTranslator):
124     """
125     Django-specific reST to HTML tweaks.
126     """
127
128     # Don't use border=1, which docutils does by default.
129     def visit_table(self, node):
130         self.body.append(self.starttag(node, 'table', CLASS='docutils'))
131
132     # <big>? Really?
133     def visit_desc_parameterlist(self, node):
134         self.body.append('(')
135         self.first_param = 1
136
137     def depart_desc_parameterlist(self, node):
138         self.body.append(')')
139
140     #
141     # Don't apply smartypants to literal blocks
142     #
143     def visit_literal_block(self, node):
144         self.no_smarty += 1
145         SmartyPantsHTMLTranslator.visit_literal_block(self, node)
146
147     def depart_literal_block(self, node):
148         SmartyPantsHTMLTranslator.depart_literal_block(self, node)
149         self.no_smarty -= 1
150
151     #
152     # Turn the "new in version" stuff (versionadded/versionchanged) into a
153     # better callout -- the Sphinx default is just a little span,
154     # which is a bit less obvious that I'd like.
155     #
156     # FIXME: these messages are all hardcoded in English. We need to change
157     # that to accomodate other language docs, but I can't work out how to make
158     # that work.
159     #
160     version_text = {
161         'deprecated':       'Deprecated in Django %s',
162         'versionchanged':   'Changed in Django %s',
163         'versionadded':     'New in Django %s',
164     }
165
166     def visit_versionmodified(self, node):
167         self.body.append(
168             self.starttag(node, 'div', CLASS=node['type'])
169         )
170         title = "%s%s" % (
171             self.version_text[node['type']] % node['version'],
172             len(node) and ":" or "."
173         )
174         self.body.append('<span class="title">%s</span> ' % title)
175
176     def depart_versionmodified(self, node):
177         self.body.append("</div>\n")
178
179     # Give each section a unique ID -- nice for custom CSS hooks
180     def visit_section(self, node):
181         old_ids = node.get('ids', [])
182         node['ids'] = ['s-' + i for i in old_ids]
183         node['ids'].extend(old_ids)
184         SmartyPantsHTMLTranslator.visit_section(self, node)
185         node['ids'] = old_ids
186
187 def parse_django_admin_node(env, sig, signode):
188     command = sig.split(' ')[0]
189     env._django_curr_admin_command = command
190     title = "django-admin.py %s" % sig
191     signode += addnodes.desc_name(title, title)
192     return sig
193
194 def parse_django_adminopt_node(env, sig, signode):
195     """A copy of sphinx.directives.CmdoptionDesc.parse_signature()"""
196     from sphinx.domains.std import option_desc_re
197     count = 0
198     firstname = ''
199     for m in option_desc_re.finditer(sig):
200         optname, args = m.groups()
201         if count:
202             signode += addnodes.desc_addname(', ', ', ')
203         signode += addnodes.desc_name(optname, optname)
204         signode += addnodes.desc_addname(args, args)
205         if not count:
206             firstname = optname
207         count += 1
208     if not count:
209         for m in simple_option_desc_re.finditer(sig):
210             optname, args = m.groups()
211             if count:
212                 signode += addnodes.desc_addname(', ', ', ')
213             signode += addnodes.desc_name(optname, optname)
214             signode += addnodes.desc_addname(args, args)
215             if not count:
216                 firstname = optname
217             count += 1
218     if not firstname:
219         raise ValueError
220     return firstname
221
222
223 class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder):
224     """
225     Subclass to add some extra things we need.
226     """
227
228     name = 'djangohtml'
229
230     def finish(self):
231         super(DjangoStandaloneHTMLBuilder, self).finish()
232         if json is None:
233             self.warn("cannot create templatebuiltins.js due to missing simplejson dependency")
234             return
235         self.info(bold("writing templatebuiltins.js..."))
236         xrefs = self.env.domaindata["std"]["objects"]
237         templatebuiltins = {
238             "ttags": [n for ((t, n), (l, a)) in xrefs.items()
239                         if t == "templatetag" and l == "ref/templates/builtins"],
240             "tfilters": [n for ((t, n), (l, a)) in xrefs.items()
241                         if t == "templatefilter" and l == "ref/templates/builtins"],
242         }
243         outfilename = os.path.join(self.outdir, "templatebuiltins.js")
244         f = open(outfilename, 'wb')
245         f.write('var django_template_builtins = ')
246         json.dump(templatebuiltins, f)
247         f.write(';\n')
248         f.close();