#!/usr/bin/env python
#
# $Id: docstring_StructuredText.py,v 1.3 2006/12/05 13:10:46 doughellmann Exp $
#
# Copyright 2001 Doug Hellmann.
#
#
# All Rights Reserved
#
# Permission to use, copy, modify, and distribute this software and
# its documentation for any purpose and without fee is hereby
# granted, provided that the above copyright notice appear in all
# copies and that both that copyright notice and this permission
# notice appear in supporting documentation, and that the name of Doug
# Hellmann not be used in advertising or publicity pertaining to
# distribution of the software without specific, written prior
# permission.
#
# DOUG HELLMANN DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
# NO EVENT SHALL DOUG HELLMANN BE LIABLE FOR ANY SPECIAL, INDIRECT OR
# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
# NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
#
"""Docstring converter for StructuredText format.
"""
__rcs_info__ = {
#
# Creation Information
#
'module_name' : '$RCSfile: docstring_StructuredText.py,v $',
'rcs_id' : '$Id: docstring_StructuredText.py,v 1.3 2006/12/05 13:10:46 doughellmann Exp $',
'creator' : 'Doug Hellmann',
'project' : 'HappyDoc',
'created' : 'Wed, 26-Sep-2001 09:52:01 EDT',
#
# Current Information
#
'author' : '$Author: doughellmann $',
'version' : '$Revision: 1.3 $',
'date' : '$Date: 2006/12/05 13:10:46 $',
}
try:
__version__ = __rcs_info__['version'].split(' ')[1]
except:
__version__ = '0.0'
#
# Import system modules
#
import re
#
# Import Local modules
#
import happydoclib.docstring.StructuredText
import happydoclib
#
# Module
#
TRACE_LEVEL=3
def entryPoint():
"Return information about this module to the dynamic loader."
return {
'name':'StructuredText',
'factory':StructuredTextConverter,
'filenamePatternList':[ '^.*\.stx$',
'^.*\.txt$',
'(README|LICENSE|ANNOUNCE|CHANGES)$',
],
}
class StructuredTextFile(happydoclib.happydocstring.ExternalDocumentationFileBase):
"""External documentation in StructuredText format.
"""
_input_type = 'StructuredText'
def __init__(self, filename, body=None):
happydoclib.happydocstring.ExternalDocumentationFileBase.__init__(
self,
filename,
body)
converted_body = happydoclib.docstring.StructuredText.Basic(self._file_contents)
one_liner_para = converted_body
while 1:
try:
if one_liner_para.getChildren():
one_liner_para = one_liner_para.getChildren()[0]
else:
break
except AttributeError:
break
self._oneliner = str(one_liner_para)
return
class StructuredTextConverter(happydoclib.happydocstring.HappyDocStringConverterBase):
"""StructuredText format converter.
This converter supports translating StructuredText (see
the StructuredText package) input to HTML output.
"""
externalDocumentFactory = StructuredTextFile
RECOGNIZED_OUTPUT_FORMATS = [ 'html' ]
def _testOutputFormat(self, outputFormat):
if outputFormat not in self.RECOGNIZED_OUTPUT_FORMATS:
raise ValueError('Unrecognized output format "%s" for %s.' % (
outputFormat,
self.__class__.__name__,
)
)
def _cleanup(self,
inputText,
extractBody=re.compile('<body>(.*)</body>', re.MULTILINE | re.DOTALL),
):
"Clean converted text and return new value."
match = extractBody.search(inputText)
if not match:
clean_text = inputText
else:
clean_text = match.group(1)
return clean_text
def _unquoteHTML( self,
text,
character_entities=( (re.compile('&'), '&'),
(re.compile("<"), '<' ),
(re.compile(">"), '>' ),
(re.compile('"'), '"')
),
):
"Reverse the quoting process for character entities."
for regex, replacement in character_entities:
text = regex.sub(replacement, text)
return text
def _unquoteExamplesInST(self, st):
"Unquote the characters in all example paragraphs in the ST tree."
try:
tag_name = st.getTagName()
except AttributeError:
return
else:
if tag_name in ('StructuredTextExample',):
actual_para = st.aq_self
text = self._unquoteHTML(actual_para._src)
actual_para._src = text
elif tag_name in ( 'StructuredTextLiteral',):
actual_para = st.aq_self
text = self._unquoteHTML(actual_para._value)
actual_para._value = text
else:
for child in st.getChildNodes():
self._unquoteExamplesInST(child)
return
def convert(self, inputText, outputFormat, level=3, *args, **namedArgs):
"""Returns the 'inputText' data translated into the 'outputFormat'.
Parameters:
'inputText' -- String or other sequence of characters to be
converted. This string should be in the format advertised
by the docstring converter.
'outputFormat' -- String defined by the docstring converter
class to represent a supported output scheme. This value is
converter-specific, and not all converters will support the
same output formats.
'level=3' -- Beginning indention level for the text. This
controls what type of header elements are created among
other behaviors.
"""
text = inputText
self._testOutputFormat(outputFormat)
if outputFormat == 'html':
applyNamedArgs = {}
applyNamedArgs.update(namedArgs)
applyNamedArgs['level'] = level
# Translate embedded references
text = re.sub(
r'[\000\n]\.\. \[([0-9_%s-]+)\]' % \
happydoclib.docstring.StructuredText.STletters.letters,
r'\n <a name="\1">[\1]</a>',
text)
text = re.sub(
r'([\000- ,])\[(?P<ref>[0-9_%s-]+)\]([\000- ,.:])' % \
happydoclib.docstring.StructuredText.STletters.letters,
r'\1<a href="#\2">[\2]</a>\3',
text)
text = re.sub(
r'([\000- ,])\[([^]]+)\.html\]([\000- ,.:])',
r'\1<a href="\2.html">[\2]</a>\3',
text)
try:
# Get the ST Document
st = happydoclib.docstring.StructuredText.Document(text)
except TypeError, msg:
# This usually means we're really looking at a
# Classic StructuredText document, so try
# falling back there.
converter_factory = happydoclib.docstring.getConverterFactory('ClassicStructuredText')
converter = converter_factory()
html_representation = converter.convert(inputText, outputFormat)
else:
# New StructuredText worked, so convert the document
# to HTML.
# First, unquote example paragraphs so they are not quoted
# twice by the HTML converter.
self._unquoteExamplesInST(st)
# Get the HTML representation
htmlng = happydoclib.docstring.StructuredText.HTMLClass.HTMLClass()
html_representation = apply( htmlng,
(st,)+args,
applyNamedArgs,
)
html_representation = str(html_representation)
html_representation = self._cleanup(html_representation)
return html_representation
return inputText
def quote(self, inputText, outputFormat, *args, **namedArgs):
"""Returns the 'inputText' quoted in a way that special characters are escaped.
Parameters:
'inputText' -- String or other sequence of characters to be
converted. This string should be in the format advertised
by the docstring converter.
'outputFormat' -- String defined by the docstring converter
class to represent a supported output scheme. This value is
converter-specific, and not all converters will support the
same output formats.
'*args' -- Additional, converter-specific, positional arguments.
'**namedArgs' -- Additional, converter-specific, named arguments.
"""
happydoclib.TRACE.into('StructuredTextConverter',
'quote',
inputText=inputText,
outputFormat=outputFormat,
args=args,
namedArgs=namedArgs,
outputLevel=TRACE_LEVEL,
)
self._testOutputFormat(outputFormat)
if outputFormat == 'html':
html_quoted = apply( happydoclib.docstring.StructuredText.html_quote,
(inputText,)+args,
namedArgs,
)
happydoclib.TRACE.write('AFTER QUOTING="%s"' % html_quoted,
outputLevel=TRACE_LEVEL)
#
# Replace form: ".*":
# with: ".*"
#
# This allows links to work.
#
html_quoted = re.sub(
'"([^&]+)":',
'"\\1":',
html_quoted)
happydoclib.TRACE.write('AFTER FIXUP="%s"' % html_quoted,
outputLevel=TRACE_LEVEL)
happydoclib.TRACE.outof(outputLevel=TRACE_LEVEL)
return html_quoted
happydoclib.TRACE.outof(outputLevel=TRACE_LEVEL)
return inputText
|