| "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) |
