Debian Codegraph @

docs/_ext/djangodocs.py

raw
1 """
2 Sphinx plugins for Django documentation.
3 """
4
5 import json
6 import os
7 import re
8
9 from docutils import nodes
10 from docutils.parsers.rst import Directive
11 from docutils.statemachine import ViewList
12 from sphinx import addnodes
13 from sphinx import version_info as sphinx_version
14 from sphinx.builders.html import StandaloneHTMLBuilder
15 from sphinx.directives.code import CodeBlock
16 from sphinx.domains.std import Cmdoption
17 from sphinx.errors import ExtensionError
18 from sphinx.util import logging
19 from sphinx.util.console import bold
20 from sphinx.writers.html import HTMLTranslator
21
22 logger = logging.getLogger(__name__)
23 # RE for option descriptions without a '--' prefix
24 simple_option_desc_re = re.compile(r"([-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)")
25
26
27 def setup(app):
28 app.add_crossref_type(
29 directivename="setting",
30 rolename="setting",
31 indextemplate="pair: %s; setting",
32 )
33 app.add_crossref_type(
34 directivename="templatetag",
35 rolename="ttag",
36 indextemplate="pair: %s; template tag",
37 )
38 app.add_crossref_type(
39 directivename="templatefilter",
40 rolename="tfilter",
41 indextemplate="pair: %s; template filter",
42 )
43 app.add_crossref_type(
44 directivename="fieldlookup",
45 rolename="lookup",
46 indextemplate="pair: %s; field lookup type",
47 )
48 app.add_object_type(
49 directivename="django-admin",
50 rolename="djadmin",
51 indextemplate="pair: %s; django-admin command",
52 parse_node=parse_django_admin_node,
53 )
54 app.add_directive("django-admin-option", Cmdoption)
55 app.add_config_value("django_next_version", "0.0", True)
56 app.add_directive("versionadded", VersionDirective)
57 app.add_directive("versionchanged", VersionDirective)
58 app.add_builder(DjangoStandaloneHTMLBuilder)
59 app.set_translator("djangohtml", DjangoHTMLTranslator)
60 app.set_translator("json", DjangoHTMLTranslator)
61 app.add_node(
62 ConsoleNode,
63 html=(visit_console_html, None),
64 latex=(visit_console_dummy, depart_console_dummy),
65 man=(visit_console_dummy, depart_console_dummy),
66 text=(visit_console_dummy, depart_console_dummy),
67 texinfo=(visit_console_dummy, depart_console_dummy),
68 )
69 app.add_directive("console", ConsoleDirective)
70 app.connect("html-page-context", html_page_context_hook)
71 app.add_role("default-role-error", default_role_error)
72 return {"parallel_read_safe": True}
73
74
75 class VersionDirective(Directive):
76 has_content = True
77 required_arguments = 1
78 optional_arguments = 1
79 final_argument_whitespace = True
80 option_spec = {}
81
82 def run(self):
83 if len(self.arguments) > 1:
84 msg = """Only one argument accepted for directive '{directive_name}::'.
85 Comments should be provided as content,
86 not as an extra argument.""".format(directive_name=self.name)
87 raise self.error(msg)
88
89 env = self.state.document.settings.env
90 ret = []
91 node = addnodes.versionmodified()
92 ret.append(node)
93
94 if self.arguments[0] == env.config.django_next_version:
95 node["version"] = "Development version"
96 else:
97 node["version"] = self.arguments[0]
98
99 node["type"] = self.name
100 if self.content:
101 self.state.nested_parse(self.content, self.content_offset, node)
102 try:
103 env.get_domain("changeset").note_changeset(node)
104 except ExtensionError:
105 # Sphinx < 1.8: Domain 'changeset' is not registered
106 env.note_versionchange(node["type"], node["version"], node, self.lineno)
107 return ret
108
109
110 class DjangoHTMLTranslator(HTMLTranslator):
111 """
112 Django-specific reST to HTML tweaks.
113 """
114
115 # Don't use border=1, which docutils does by default.
116 def visit_table(self, node):
117 self.context.append(self.compact_p)
118 self.compact_p = True
119 # Needed by Sphinx.
120 self._table_row_indices.append(0)
121 self.body.append(self.starttag(node, "table", CLASS="docutils"))
122
123 def depart_table(self, node):
124 self.compact_p = self.context.pop()
125 self._table_row_indices.pop()
126 self.body.append("</table>\n")
127
128 def visit_desc_parameterlist(self, node):
129 self.body.append("(") # by default sphinx puts <big> around the "("
130 self.optional_param_level = 0
131 self.param_separator = node.child_text_separator
132 # Counts 'parameter groups' being either a required parameter, or a set
133 # of contiguous optional ones.
134 required_params = [
135 isinstance(c, addnodes.desc_parameter) for c in node.children
136 ]
137 # How many required parameters are left.
138 self.required_params_left = sum(required_params)
139 if sphinx_version < (7, 1):
140 self.first_param = 1
141 else:
142 self.is_first_param = True
143 self.params_left_at_level = 0
144 self.param_group_index = 0
145 self.list_is_required_param = required_params
146 self.multi_line_parameter_list = False
147
148 def depart_desc_parameterlist(self, node):
149 self.body.append(")")
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 accommodate other language docs, but I can't work out how to make
158 # that work.
159 #
160 version_text = {
161 "versionchanged": "Changed in Django %s",
162 "versionadded": "New in Django %s",
163 }
164
165 def visit_versionmodified(self, node):
166 self.body.append(self.starttag(node, "div", CLASS=node["type"]))
167 version_text = self.version_text.get(node["type"])
168 if version_text:
169 title = "%s%s" % (version_text % node["version"], ":" if len(node) else ".")
170 self.body.append('<span class="title">%s</span> ' % title)
171
172 def depart_versionmodified(self, node):
173 self.body.append("</div>\n")
174
175 # Give each section a unique ID -- nice for custom CSS hooks
176 def visit_section(self, node):
177 old_ids = node.get("ids", [])
178 node["ids"] = ["s-" + i for i in old_ids]
179 node["ids"].extend(old_ids)
180 super().visit_section(node)
181 node["ids"] = old_ids
182
183
184 def parse_django_admin_node(env, sig, signode):
185 command = sig.split(" ")[0]
186 env.ref_context["std:program"] = command
187 title = "django-admin %s" % sig
188 signode += addnodes.desc_name(title, title)
189 return command
190
191
192 class DjangoStandaloneHTMLBuilder(StandaloneHTMLBuilder):
193 """
194 Subclass to add some extra things we need.
195 """
196
197 name = "djangohtml"
198
199 def finish(self):
200 super().finish()
201 logger.info(bold("writing templatebuiltins.js..."))
202 xrefs = self.env.domaindata["std"]["objects"]
203 templatebuiltins = {
204 "ttags": [
205 n
206 for ((t, n), (k, a)) in xrefs.items()
207 if t == "templatetag" and k == "ref/templates/builtins"
208 ],
209 "tfilters": [
210 n
211 for ((t, n), (k, a)) in xrefs.items()
212 if t == "templatefilter" and k == "ref/templates/builtins"
213 ],
214 }
215 outfilename = os.path.join(self.outdir, "templatebuiltins.js")
216 with open(outfilename, "w") as fp:
217 fp.write("var django_template_builtins = ")
218 json.dump(templatebuiltins, fp)
219 fp.write(";\n")
220
221
222 class ConsoleNode(nodes.literal_block):
223 """
224 Custom node to override the visit/depart event handlers at registration
225 time. Wrap a literal_block object and defer to it.
226 """
227
228 tagname = "ConsoleNode"
229
230 def __init__(self, litblk_obj):
231 self.wrapped = litblk_obj
232
233 def __getattr__(self, attr):
234 if attr == "wrapped":
235 return self.__dict__.wrapped
236 return getattr(self.wrapped, attr)
237
238
239 def visit_console_dummy(self, node):
240 """Defer to the corresponding parent's handler."""
241 self.visit_literal_block(node)
242
243
244 def depart_console_dummy(self, node):
245 """Defer to the corresponding parent's handler."""
246 self.depart_literal_block(node)
247
248
249 def visit_console_html(self, node):
250 """Generate HTML for the console directive."""
251 if self.builder.name in ("djangohtml", "json") and node["win_console_text"]:
252 # Put a mark on the document object signaling the fact the directive
253 # has been used on it.
254 self.document._console_directive_used_flag = True
255 uid = node["uid"]
256 self.body.append("""\
257 <div class="console-block" id="console-block-%(id)s">
258 <input class="c-tab-unix" id="c-tab-%(id)s-unix" type="radio" name="console-%(id)s" \
259 checked>
260 <label for="c-tab-%(id)s-unix" title="Linux/macOS">&#xf17c/&#xf179</label>
261 <input class="c-tab-win" id="c-tab-%(id)s-win" type="radio" name="console-%(id)s">
262 <label for="c-tab-%(id)s-win" title="Windows">&#xf17a</label>
263 <section class="c-content-unix" id="c-content-%(id)s-unix">\n""" % {"id": uid})
264 try:
265 self.visit_literal_block(node)
266 except nodes.SkipNode:
267 pass
268 self.body.append("</section>\n")
269
270 self.body.append(
271 '<section class="c-content-win" id="c-content-%(id)s-win">\n' % {"id": uid}
272 )
273 win_text = node["win_console_text"]
274 highlight_args = {"force": True}
275 linenos = node.get("linenos", False)
276
277 def warner(msg):
278 self.builder.warn(msg, (self.builder.current_docname, node.line))
279
280 highlighted = self.highlighter.highlight_block(
281 win_text, "doscon", warn=warner, linenos=linenos, **highlight_args
282 )
283 self.body.append(highlighted)
284 self.body.append("</section>\n")
285 self.body.append("</div>\n")
286 raise nodes.SkipNode
287 else:
288 self.visit_literal_block(node)
289
290
291 class ConsoleDirective(CodeBlock):
292 """
293 A reStructuredText directive which renders a two-tab code block in which
294 the second tab shows a Windows command line equivalent of the usual
295 Unix-oriented examples.
296 """
297
298 required_arguments = 0
299 # The 'doscon' Pygments formatter needs a prompt like this. '>' alone
300 # won't do it because then it simply paints the whole command line as a
301 # gray comment with no highlighting at all.
302 WIN_PROMPT = r"...\> "
303
304 def run(self):
305 def args_to_win(cmdline):
306 changed = False
307 out = []
308 for token in cmdline.split():
309 if token[:2] == "./":
310 token = token[2:]
311 changed = True
312 elif token[:2] == "~/":
313 token = "%HOMEPATH%\\" + token[2:]
314 changed = True
315 elif token == "make":
316 token = "make.bat"
317 changed = True
318 if "://" not in token and "git" not in cmdline:
319 out.append(token.replace("/", "\\"))
320 changed = True
321 else:
322 out.append(token)
323 if changed:
324 return " ".join(out)
325 return cmdline
326
327 def cmdline_to_win(line):
328 if line.startswith("# "):
329 return "REM " + args_to_win(line[2:])
330 if line.startswith("$ # "):
331 return "REM " + args_to_win(line[4:])
332 if line.startswith("$ ./manage.py"):
333 return "manage.py " + args_to_win(line[13:])
334 if line.startswith("$ manage.py"):
335 return "manage.py " + args_to_win(line[11:])
336 if line.startswith("$ ./runtests.py"):
337 return "runtests.py " + args_to_win(line[15:])
338 if line.startswith("$ ./"):
339 return args_to_win(line[4:])
340 if line.startswith("$ python3"):
341 return "py " + args_to_win(line[9:])
342 if line.startswith("$ python"):
343 return "py " + args_to_win(line[8:])
344 if line.startswith("$ "):
345 return args_to_win(line[2:])
346 return None
347
348 def code_block_to_win(content):
349 bchanged = False
350 lines = []
351 for line in content:
352 modline = cmdline_to_win(line)
353 if modline is None:
354 lines.append(line)
355 else:
356 lines.append(self.WIN_PROMPT + modline)
357 bchanged = True
358 if bchanged:
359 return ViewList(lines)
360 return None
361
362 env = self.state.document.settings.env
363 self.arguments = ["console"]
364 lit_blk_obj = super().run()[0]
365
366 # Only do work when the djangohtml HTML Sphinx builder is being used,
367 # invoke the default behavior for the rest.
368 if env.app.builder.name not in ("djangohtml", "json"):
369 return [lit_blk_obj]
370
371 lit_blk_obj["uid"] = str(env.new_serialno("console"))
372 # Only add the tabbed UI if there is actually a Windows-specific
373 # version of the CLI example.
374 win_content = code_block_to_win(self.content)
375 if win_content is None:
376 lit_blk_obj["win_console_text"] = None
377 else:
378 self.content = win_content
379 lit_blk_obj["win_console_text"] = super().run()[0].rawsource
380
381 # Replace the literal_node object returned by Sphinx's CodeBlock with
382 # the ConsoleNode wrapper.
383 return [ConsoleNode(lit_blk_obj)]
384
385
386 def html_page_context_hook(app, pagename, templatename, context, doctree):
387 # Put a bool on the context used to render the template. It's used to
388 # control inclusion of console-tabs.css and activation of the JavaScript.
389 # This way it's include only from HTML files rendered from reST files where
390 # the ConsoleDirective is used.
391 context["include_console_assets"] = getattr(
392 doctree, "_console_directive_used_flag", False
393 )
394
395
396 def default_role_error(
397 name, rawtext, text, lineno, inliner, options=None, content=None
398 ):
399 msg = (
400 "Default role used (`single backticks`): %s. Did you mean to use two "
401 "backticks for ``code``, or miss an underscore for a `link`_ ?" % rawtext
402 )
403 logger.warning(msg, location=(inliner.document.current_source, lineno))
404 return [nodes.Text(text)], []