djangodocs.py 3.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105
  1. """
  2. Sphinx plugins for Django documentation.
  3. """
  4. import docutils.nodes
  5. import docutils.transforms
  6. import sphinx
  7. import sphinx.addnodes
  8. import sphinx.directives
  9. import sphinx.environment
  10. import sphinx.roles
  11. from docutils import nodes
  12. def setup(app):
  13. app.add_crossref_type(
  14. directivename = "setting",
  15. rolename = "setting",
  16. indextemplate = "pair: %s; setting",
  17. )
  18. app.add_crossref_type(
  19. directivename = "templatetag",
  20. rolename = "ttag",
  21. indextemplate = "pair: %s; template tag"
  22. )
  23. app.add_crossref_type(
  24. directivename = "templatefilter",
  25. rolename = "tfilter",
  26. indextemplate = "pair: %s; template filter"
  27. )
  28. app.add_crossref_type(
  29. directivename = "fieldlookup",
  30. rolename = "lookup",
  31. indextemplate = "pair: %s, field lookup type",
  32. )
  33. app.add_description_unit(
  34. directivename = "django-admin",
  35. rolename = "djadmin",
  36. indextemplate = "pair: %s; django-admin command",
  37. parse_node = parse_django_admin_node,
  38. )
  39. app.add_description_unit(
  40. directivename = "django-admin-option",
  41. rolename = "djadminopt",
  42. indextemplate = "pair: %s; django-admin command-line option",
  43. parse_node = lambda env, sig, signode: sphinx.directives.parse_option_desc(signode, sig),
  44. )
  45. app.add_config_value('django_next_version', '0.0', True)
  46. app.add_directive('versionadded', parse_version_directive, 1, (1, 1, 1))
  47. app.add_directive('versionchanged', parse_version_directive, 1, (1, 1, 1))
  48. app.add_transform(SuppressBlockquotes)
  49. def parse_version_directive(name, arguments, options, content, lineno,
  50. content_offset, block_text, state, state_machine):
  51. env = state.document.settings.env
  52. is_nextversion = env.config.django_next_version == arguments[0]
  53. ret = []
  54. node = sphinx.addnodes.versionmodified()
  55. ret.append(node)
  56. if not is_nextversion:
  57. if len(arguments) == 1:
  58. linktext = 'Please, see the release notes <releases-%s>' % (arguments[0])
  59. xrefs = sphinx.roles.xfileref_role('ref', linktext, linktext, lineno, state)
  60. node.extend(xrefs[0])
  61. node['version'] = arguments[0]
  62. else:
  63. node['version'] = "Development version"
  64. node['type'] = name
  65. if len(arguments) == 2:
  66. inodes, messages = state.inline_text(arguments[1], lineno+1)
  67. node.extend(inodes)
  68. if content:
  69. state.nested_parse(content, content_offset, node)
  70. ret = ret + messages
  71. env.note_versionchange(node['type'], node['version'], node, lineno)
  72. return ret
  73. class SuppressBlockquotes(docutils.transforms.Transform):
  74. """
  75. Remove the default blockquotes that encase indented list, tables, etc.
  76. """
  77. default_priority = 300
  78. suppress_blockquote_child_nodes = (
  79. docutils.nodes.bullet_list,
  80. docutils.nodes.enumerated_list,
  81. docutils.nodes.definition_list,
  82. docutils.nodes.literal_block,
  83. docutils.nodes.doctest_block,
  84. docutils.nodes.line_block,
  85. docutils.nodes.table
  86. )
  87. def apply(self):
  88. for node in self.document.traverse(docutils.nodes.block_quote):
  89. if len(node.children) == 1 and isinstance(node.children[0], self.suppress_blockquote_child_nodes):
  90. node.replace_self(node.children[0])
  91. def parse_django_admin_node(env, sig, signode):
  92. command = sig.split(' ')[0]
  93. env._django_curr_admin_command = command
  94. title = "django-admin.py %s" % sig
  95. signode += sphinx.addnodes.desc_name(title, title)
  96. return sig