app/django/contrib/admindocs/utils.py

   1 "Misc. utility functions/classes for admin documentation generator."
   2
   3 import re
   4 from email.Parser import HeaderParser
   5 from email.Errors import HeaderParseError
   6 from django.utils.safestring import mark_safe
   7 try:
   8     import docutils.core
   9     import docutils.nodes
  10     import docutils.parsers.rst.roles
  11 except ImportError:
  12     docutils_is_available = False
  13 else:
  14     docutils_is_available = True
  15
  16 def trim_docstring(docstring):
  17     """
  18     Uniformly trims leading/trailing whitespace from docstrings.
  19
  20     Based on http://www.python.org/peps/pep-0257.html#handling-docstring-indentation
  21     """
  22     if not docstring or not docstring.strip():
  23         return ''
  24     # Convert tabs to spaces and split into lines
  25     lines = docstring.expandtabs().splitlines()
  26     indent = min([len(line) - len(line.lstrip()) for line in lines if line.lstrip()])
  27     trimmed = [lines[0].lstrip()] + [line[indent:].rstrip() for line in lines[1:]]
  28     return "\n".join(trimmed).strip()
  29
  30 def parse_docstring(docstring):
  31     """
  32     Parse out the parts of a docstring.  Returns (title, body, metadata).
  33     """
  34     docstring = trim_docstring(docstring)
  35     parts = re.split(r'\n{2,}', docstring)
  36     title = parts[0]
  37     if len(parts) == 1:
  38         body = ''
  39         metadata = {}
  40     else:
  41         parser = HeaderParser()
  42         try:
  43             metadata = parser.parsestr(parts[-1])
  44         except HeaderParseError:
  45             metadata = {}
  46             body = "\n\n".join(parts[1:])
  47         else:
  48             metadata = dict(metadata.items())
  49             if metadata:
  50                 body = "\n\n".join(parts[1:-1])
  51             else:
  52                 body = "\n\n".join(parts[1:])
  53     return title, body, metadata
  54
  55 def parse_rst(text, default_reference_context, thing_being_parsed=None, link_base='../..'):
  56     """
  57     Convert the string from reST to an XHTML fragment.
  58     """
  59     overrides = {
  60         'doctitle_xform' : True,
  61         'inital_header_level' : 3,
  62         "default_reference_context" : default_reference_context,
  63         "link_base" : link_base,
  64     }
  65     if thing_being_parsed:
  66         thing_being_parsed = "<%s>" % thing_being_parsed
  67     parts = docutils.core.publish_parts(text, source_path=thing_being_parsed,
  68                 destination_path=None, writer_name='html',
  69                 settings_overrides=overrides)
  70     return mark_safe(parts['fragment'])
  71
  72 #
  73 # reST roles
  74 #
  75 ROLES = {
  76     'model'    : '%s/models/%s/',
  77     'view'     : '%s/views/%s/',
  78     'template' : '%s/templates/%s/',
  79     'filter'   : '%s/filters/#%s',
  80     'tag'      : '%s/tags/#%s',
  81 }
  82
  83 def create_reference_role(rolename, urlbase):
  84     def _role(name, rawtext, text, lineno, inliner, options=None, content=None):
  85         if options is None: options = {}
  86         if content is None: content = []
  87         node = docutils.nodes.reference(rawtext, text, refuri=(urlbase % (inliner.document.settings.link_base, text.lower())), **options)
  88         return [node], []
  89     docutils.parsers.rst.roles.register_canonical_role(rolename, _role)
  90
  91 def default_reference_role(name, rawtext, text, lineno, inliner, options=None, content=None):
  92     if options is None: options = {}
  93     if content is None: content = []
  94     context = inliner.document.settings.default_reference_context
  95     node = docutils.nodes.reference(rawtext, text, refuri=(ROLES[context] % (inliner.document.settings.link_base, text.lower())), **options)
  96     return [node], []
  97
  98 if docutils_is_available:
  99     docutils.parsers.rst.roles.register_canonical_role('cmsreference', default_reference_role)
 100     docutils.parsers.rst.roles.DEFAULT_INTERPRETED_ROLE = 'cmsreference'
 101
 102     for name, urlbase in ROLES.items():
 103         create_reference_role(name, urlbase)