| 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">/</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"></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)], [] |