"Misc. utility functions/classes for admin documentation generator."

import re

from email.Parser import HeaderParser

from email.Errors import HeaderParseError

from django.utils.safestring import mark_safe

try:

    import docutils.core

    import docutils.nodes

    import docutils.parsers.rst.roles

except ImportError:

    docutils_is_available = False

else:

    docutils_is_available = True

def trim_docstring(docstring):

    """

    Uniformly trims leading/trailing whitespace from docstrings.

    Based on http://www.python.org/peps/pep-0257.html#handling-docstring-indentation

    """

    if not docstring or not docstring.strip():

        return ''

    # Convert tabs to spaces and split into lines

    lines = docstring.expandtabs().splitlines()

    indent = min([len(line) - len(line.lstrip()) for line in lines if line.lstrip()])

    trimmed = [lines[0].lstrip()] + [line[indent:].rstrip() for line in lines[1:]]

    return "\n".join(trimmed).strip()

def parse_docstring(docstring):

    """

    Parse out the parts of a docstring.  Returns (title, body, metadata).

    """

    docstring = trim_docstring(docstring)

    parts = re.split(r'\n{2,}', docstring)

    title = parts[0]

    if len(parts) == 1:

        body = ''

        metadata = {}

    else:

        parser = HeaderParser()

        try:

            metadata = parser.parsestr(parts[-1])

        except HeaderParseError:

            metadata = {}

            body = "\n\n".join(parts[1:])

        else:

            metadata = dict(metadata.items())

            if metadata:

                body = "\n\n".join(parts[1:-1])

            else:

                body = "\n\n".join(parts[1:])

    return title, body, metadata

def parse_rst(text, default_reference_context, thing_being_parsed=None, link_base='../..'):

    """

    Convert the string from reST to an XHTML fragment.

    """

    overrides = {

        'doctitle_xform' : True,

        'inital_header_level' : 3,

        "default_reference_context" : default_reference_context,

        "link_base" : link_base,

    }

    if thing_being_parsed:

        thing_being_parsed = "<%s>" % thing_being_parsed

    parts = docutils.core.publish_parts(text, source_path=thing_being_parsed,

                destination_path=None, writer_name='html',

                settings_overrides=overrides)

    return mark_safe(parts['fragment'])

#

# reST roles

#

ROLES = {

    'model'    : '%s/models/%s/',

    'view'     : '%s/views/%s/',

    'template' : '%s/templates/%s/',

    'filter'   : '%s/filters/#%s',

    'tag'      : '%s/tags/#%s',

}

def create_reference_role(rolename, urlbase):

    def _role(name, rawtext, text, lineno, inliner, options=None, content=None):

        if options is None: options = {}

        if content is None: content = []

        node = docutils.nodes.reference(rawtext, text, refuri=(urlbase % (inliner.document.settings.link_base, text.lower())), **options)

        return [node], []

    docutils.parsers.rst.roles.register_canonical_role(rolename, _role)

def default_reference_role(name, rawtext, text, lineno, inliner, options=None, content=None):

    if options is None: options = {}

    if content is None: content = []

    context = inliner.document.settings.default_reference_context

    node = docutils.nodes.reference(rawtext, text, refuri=(ROLES[context] % (inliner.document.settings.link_base, text.lower())), **options)

    return [node], []

if docutils_is_available:

    docutils.parsers.rst.roles.register_canonical_role('cmsreference', default_reference_role)

    docutils.parsers.rst.roles.DEFAULT_INTERPRETED_ROLE = 'cmsreference'

    for name, urlbase in ROLES.items():

        create_reference_role(name, urlbase)