# # $Id: docstring_ClassicStructuredText.py,v 1.2 2001/10/28 13:40:25 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 original StructuredText format. """ __rcs_info__ = { # # Creation Information # 'module_name' : '$RCSfile: docstring_ClassicStructuredText.py,v $', 'rcs_id' : '$Id: docstring_ClassicStructuredText.py,v 1.2 2001/10/28 13:40:25 doughellmann Exp $', 'creator' : 'Doug Hellmann ', 'project' : 'HappyDoc', 'created' : 'Wed, 26-Sep-2001 09:52:01 EDT', # # Current Information # 'author' : '$Author: doughellmann $', 'version' : '$Revision: 1.2 $', 'date' : '$Date: 2001/10/28 13:40:25 $', } try: __version__ = __rcs_info__['version'].split(' ')[1] except: __version__ = '0.0' # # Import system modules # import re # # Import Local modules # import happydoclib # # Module # def entryPoint(): "Return information about this module to the dynamic loader." return { 'name':'ClassicStructuredText', 'factory':ClassicStructuredTextConverter, 'filenamePatternList':[ ], } class ClassicStructuredTextFile(happydoclib.happydocstring.ExternalDocumentationFileBase): """External documentation in StructuredText format. """ _input_type = 'ClassicStructuredText' def __init__(self, filename, body=None): import happydoclib.docstring.StructuredText.ClassicStructuredText StructuredText = happydoclib.docstring.StructuredText.ClassicStructuredText happydoclib.happydocstring.ExternalDocumentationFileBase.__init__( self, filename, body) converted_body = StructuredText.StructuredText(self._file_contents) self._oneliner = str(converted_body.structure[0][0]) return class ClassicStructuredTextConverter(happydoclib.happydocstring.HappyDocStringConverterBase): """Classic StructuredText format converter. This converter supports translating StructuredText (see happydoc/hddocstring/StructuredText/ClassicStructuredText.py) input to HTML output. """ externalDocumentFactory = ClassicStructuredTextFile 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 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. """ self._testOutputFormat(outputFormat) import happydoclib.docstring.StructuredText.ClassicStructuredText StructuredText = happydoclib.docstring.StructuredText.ClassicStructuredText if outputFormat == 'html': applyNamedArgs = {} applyNamedArgs.update(namedArgs) applyNamedArgs['level'] = level html_representation = apply( StructuredText.html_with_references, (inputText,)+args, applyNamedArgs, ) return str(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. """ self._testOutputFormat(outputFormat) import happydoclib.docstring.StructuredText.ClassicStructuredText StructuredText = happydoclib.docstring.StructuredText.ClassicStructuredText if outputFormat == 'html': html_quoted = apply( StructuredText.html_quote, (inputText,)+args, namedArgs, ) # # Replace form: ".*": # with: ".*" # # This allows links to work. # html_quoted = re.sub( '"([^&]+)":', '"\\1":', html_quoted) return html_quoted return inputText class ClassicSTUnitTest(happydoclib.happydocstring.DocStringConverterTest): expectedOutput = '''

"""Classic Structured Text Manipulation

Parse a structured text string into a form that can be used with structured formats, like html.

Structured text is text that uses indentation and simple symbology to indicate the structure of a document.

A structured string consists of a sequence of paragraphs separated by one or more blank lines. Each paragraph has a level which is defined as the minimum indentation of the paragraph. A paragraph is a sub-paragraph of another paragraph if the other paragraph is the last preceding paragraph that has a lower level.

Special symbology is used to indicate special constructs:

"""

''' def testClassicStructuredTextConversion(self): filename = 'TestCases/test_classic_structuredtext.py' import happydoclib.parseinfo parsed_module = happydoclib.parseinfo.getDocs(filename) input_text = parsed_module._docstring self._testConversion( input_text, 'ClassicStructuredText', 'html', self.expectedOutput, 'Converting Classic ST to HTML did not produce expected results.', ) return def testBug471981Classic(self): input_text1 = """ any text first heading first section second heading second section third heading third section """ expected_text1 = '''

any text

first heading

first section

second heading

second section

third heading

third section

''' self._testConversion( input_text1, 'ClassicStructuredText', 'html', expected_text1, 'Converting Classic ST to HTML did not produce expected results.', ) input_text2 = """ first heading first section second heading second section third heading third section """ expected_text2 = '''

first heading

first section

second heading

second section

third heading

third section

''' self._testConversion( input_text2, 'ClassicStructuredText', 'html', expected_text2, 'Converting Classic ST to HTML did not produce expected results.', ) return