#!/usr/bin/env python
#
# $Id: test_docstring_StructuredText.py,v 1.1 2006/12/05 13:22:12 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: test_docstring_StructuredText.py,v $',
'rcs_id' : '$Id: test_docstring_StructuredText.py,v 1.1 2006/12/05 13:22:12 doughellmann Exp $',
'creator' : 'Doug Hellmann',
'project' : 'HappyDoc',
'created' : 'Wed, 26-Sep-2001 09:52:01 EDT',
#
# Current Information
#
'author' : '$Author: doughellmann $',
'version' : '$Revision: 1.1 $',
'date' : '$Date: 2006/12/05 13:22:12 $',
}
try:
__version__ = __rcs_info__['version'].split(' ')[1]
except:
__version__ = '0.0'
#
# Import system modules
#
#
# Import Local modules
#
import happydoclib.docstring.StructuredText
import happydoclib
class StructuredTextUnitTest(happydoclib.happydocstring.DocStringConverterTest):
html_quote_text = '<>&"\'[]{};'
html_quote_expected_text = "<>&"'[]{};"
st_test_text_with_links = '''
Structured Text With Links
This "link":link.html points to link.html.
This [1] reference points to an internal reference.
.. [1] This is the internal reference.
'''
st_expected_text_with_links = '''
<h3> Structured Text With Links</h3>
<p> This <a href="link.html">link</a> points to link.html.</p>
<p> This <a href="#1"><a href="#ref1">[1]</a></a> reference points to an internal reference.</p>
<p> <a name="1"><a href="#ref1">[1]</a></a> This is the internal reference.</p>
'''
st_test_text = '''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:
- A single-line paragraph whose immediately succeeding paragraphs are lower
level is treated as a header.
- A paragraph that begins with a '-', '*', or 'o' is treated as an
unordered list (bullet) element.
- A paragraph that begins with a sequence of digits followed by a
white-space character is treated as an ordered list element.
- A paragraph that begins with a sequence of sequences, where each
sequence is a sequence of digits or a sequence of letters followed
by a period, is treated as an ordered list element.
- A paragraph with a first line that contains some text, followed by
some white-space and '--' is treated as
a descriptive list element. The leading text is treated as the
element title.
- Sub-paragraphs of a paragraph that ends in the word 'example' or the
word 'examples', or '::' is treated as example code and is output as is.
- Text enclosed single quotes (with white-space to the left of the
first quote and whitespace or puctuation to the right of the second quote)
is treated as example code.
- Text surrounded by '*' characters (with white-space to the left of the
first '*' and whitespace or puctuation to the right of the second '*')
is emphasized.
- Text surrounded by '**' characters (with white-space to the left of the
first '**' and whitespace or puctuation to the right of the second '**')
is made strong.
- Text surrounded by '_' underscore characters (with whitespace to the left
and whitespace or punctuation to the right) is made underlined.
- Text encloded by double quotes followed by a colon, a URL, and concluded
by punctuation plus white space, *or* just white space, is treated as a
hyper link. For example:
"Zope":http://www.zope.org/ is ...
Is interpreted as '<a href="http://www.zope.org/">Zope</a> is ....'
Note: This works for relative as well as absolute URLs.
- Text enclosed by double quotes followed by a comma, one or more spaces,
an absolute URL and concluded by punctuation plus white space, or just
white space, is treated as a hyper link. For example:
"mail me", mailto:amos@digicool.com.
Is interpreted as '<a href="mailto:amos@digicool.com">mail me</a>.'
- Text enclosed in brackets which consists only of letters, digits,
underscores and dashes is treated as hyper links within the document.
For example:
As demonstrated by Smith [12] this technique is quite effective.
Is interpreted as '... by Smith <a href="#12">[12]</a> this ...'. Together
with the next rule this allows easy coding of references or end notes.
- Text enclosed in brackets which is preceded by the start of a line, two
periods and a space is treated as a named link. For example:
.. [12] "Effective Techniques" Smith, Joe ...
Is interpreted as '<a name="12">[12]</a> "Effective Techniques" ...'.
Together with the previous rule this allows easy coding of references or
end notes.
- A paragraph that has blocks of text enclosed in '||' is treated as a
table. The text blocks correspond to table cells and table rows are
denoted by newlines. By default the cells are center aligned. A cell
can span more than one column by preceding a block of text with an
equivalent number of cell separators '||'. Newlines and '|' cannot
be a part of the cell text. For example:
|||| **Ingredients** ||
|| *Name* || *Amount* ||
||Spam||10||
||Eggs||3||
is interpreted as::
<TABLE BORDER=1 CELLPADDING=2>
<TR>
<TD ALIGN=CENTER COLSPAN=2> <strong>Ingredients</strong> </TD>
</TR>
<TR>
<TD ALIGN=CENTER COLSPAN=1> <em>Name</em> </TD>
<TD ALIGN=CENTER COLSPAN=1> <em>Amount</em> </TD>
</TR>
<TR>
<TD ALIGN=CENTER COLSPAN=1>Spam</TD>
<TD ALIGN=CENTER COLSPAN=1>10</TD>
</TR>
<TR>
<TD ALIGN=CENTER COLSPAN=1>Eggs</TD>
<TD ALIGN=CENTER COLSPAN=1>3</TD>
</TR>
</TABLE>'''
st_expected_text = '''
<p>Structured Text Manipulation</p>
<p>Parse a structured text string into a form that can be used with
structured formats, like html.</p>
<p>Structured text is text that uses indentation and simple
symbology to indicate the structure of a document. </p>
<p>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.</p>
<p>Special symbology is used to indicate special constructs:</p>
<ul>
<li>A single-line paragraph whose immediately succeeding paragraphs are lower
level is treated as a header.</li>
<li>A paragraph that begins with a '-', <code>*</code>, or <code>o</code> is treated as an
unordered list (bullet) element.</li>
<li>A paragraph that begins with a sequence of digits followed by a
white-space character is treated as an ordered list element.</li>
<li>A paragraph that begins with a sequence of sequences, where each
sequence is a sequence of digits or a sequence of letters followed
by a period, is treated as an ordered list element.</li>
<li>A paragraph with a first line that contains some text, followed by
some white-space and <code>--</code> is treated as
a descriptive list element. The leading text is treated as the
element title.</li>
<li>Sub-paragraphs of a paragraph that ends in the word <code>example</code> or the
word <code>examples</code>, or <code>::</code> is treated as example code and is output as is.</li>
<li>Text enclosed single quotes (with white-space to the left of the
first quote and whitespace or puctuation to the right of the second quote)
is treated as example code.</li>
<li>Text surrounded by <code>*</code> characters (with white-space to the left of the
first <code>*</code> and whitespace or puctuation to the right of the second <code>*</code>)
is emphasized.</li>
<li>Text surrounded by <code>**</code> characters (with white-space to the left of the
first <code>**</code> and whitespace or puctuation to the right of the second <code>**</code>)
is made strong.</li>
<li>Text surrounded by <code>_</code> underscore characters (with whitespace to the left
and whitespace or punctuation to the right) is made underlined.</li>
<li>Text encloded by double quotes followed by a colon, a URL, and concluded
by punctuation plus white space, <em>or</em> just white space, is treated as a
hyper link. For example:<p> <a href="http://www.zope.org/">Zope</a> is ...</p>
<p> Is interpreted as '<a href="http://www.zope.org/">Zope</a> is ....'
Note: This works for relative as well as absolute URLs.</p>
</li>
<li>Text enclosed by double quotes followed by a comma, one or more spaces,
an absolute URL and concluded by punctuation plus white space, or just
white space, is treated as a hyper link. For example: <p> <a href="mailto:amos@digicool.com">mail me</a>.</p>
<p> Is interpreted as '<a href="mailto:amos@digicool.com">mail me</a>.' </p>
</li>
<li>Text enclosed in brackets which consists only of letters, digits,
underscores and dashes is treated as hyper links within the document.
For example:<p> As demonstrated by Smith <a href="#12"><a href="#ref12">[12]</a></a> this technique is quite effective.</p>
<p> Is interpreted as '... by Smith <a href="#12"><a href="#ref12">[12]</a></a> this ...'. Together
with the next rule this allows easy coding of references or end notes.</p>
</li>
<li>Text enclosed in brackets which is preceded by the start of a line, two
periods and a space is treated as a named link. For example:<p> .. <a href="#12"><a href="#ref12">[12]</a></a> "Effective Techniques" Smith, Joe ... </p>
<p> Is interpreted as '<a name="12"><a href="#ref12">[12]</a></a> "Effective Techniques" ...'.
Together with the previous rule this allows easy coding of references or
end notes. </p>
</li>
<li>A paragraph that has blocks of text enclosed in <code>||</code> is treated as a
table. The text blocks correspond to table cells and table rows are
denoted by newlines. By default the cells are center aligned. A cell
can span more than one column by preceding a block of text with an
equivalent number of cell separators <code>||</code>. Newlines and <code>|</code> cannot
be a part of the cell text. For example:<p> |||| <strong>Ingredients</strong> ||
|| <em>Name</em> || <em>Amount</em> ||
||Spam||10||
||Eggs||3||</p>
<p> is interpreted as:
<pre>
<TABLE BORDER=1 CELLPADDING=2>
<TR>
<TD ALIGN=CENTER COLSPAN=2> <strong>Ingredients</strong> </TD>
</TR>
<TR>
<TD ALIGN=CENTER COLSPAN=1> <em>Name</em> </TD>
<TD ALIGN=CENTER COLSPAN=1> <em>Amount</em> </TD>
</TR>
<TR>
<TD ALIGN=CENTER COLSPAN=1>Spam</TD>
<TD ALIGN=CENTER COLSPAN=1>10</TD>
</TR>
<TR>
<TD ALIGN=CENTER COLSPAN=1>Eggs</TD>
<TD ALIGN=CENTER COLSPAN=1>3</TD>
</TR>
</TABLE>
</pre>
</p>
</li>
</ul>
'''
def testConvertStructuredTextToHTML(self):
self._testConversion( self.st_test_text, 'StructuredText',
'html', self.st_expected_text,
'StructuredText-to-HTML conversion failed.'
)
return
def testConvertStructuredTextToHTMLWithLinks(self):
self._testConversion( self.st_test_text_with_links, 'StructuredText',
'html', self.st_expected_text_with_links,
'StructuredText-to-HTML-with-links conversion failed.',
)
return
def testQuoteStructuredTextToHTML(self):
self._testQuote(self.html_quote_text, 'StructuredText', 'html',
self.html_quote_expected_text,
'ST-to-HTML quote failed.',
)
return
def testStructuredTextOneLiner(self):
stf = StructuredTextFile(filename='internal', body=self.st_test_text)
assert stf, 'Unable to create valid StructuredTextFile'
expected_oneliner = 'Structured Text Manipulation'
assert stf.oneLiner() == expected_oneliner, 'Got different one-liner "%s"' % stf.oneLiner()
return
def testBug594026(self):
input_text = '*mari* or **mari**'
expected_text = '''
<p><em>mari</em> or <strong>mari</strong></p>
'''
self._testConversion(input_text,
'StructuredText',
'html',
expected_text,
'StructuredText-to-HTML with accented characters failed.',
)
return
def testBug471981(self):
input_text1 = """ any text
first heading
first
section
second heading
second
section
third heading
third
section
"""
expected_text1 = '''
<h3> any text</h3>
<p> first
section</p>
<h3>first heading</h3>
<p> second
section</p>
<h3>second heading</h3>
<p> third
section</p>
<p>third heading</p>
'''
self._testConversion(
input_text1,
'StructuredText',
'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 = '''
<h3>first heading</h3>
<p> first
section</p>
<h3>second heading</h3>
<p> second
section</p>
<h3>third heading</h3>
<p> third
section</p>
'''
self._testConversion(
input_text2,
'StructuredText',
'html',
expected_text2,
'Converting Classic ST to HTML did not produce expected results.',
)
return
def testWithQuotableCharacters(self):
input_text = "Here are some quotable characters. & < > < >."
expected_text = '\n<p>Here are some quotable characters. & < > < >.</p>\n'
self._testConversion(
input_text,
'StructuredText',
'html',
expected_text,
'Converting ST to HTML with quotable characters did not produce expected results.',
)
def testWithQuotableCharactersInExample(self):
input_text = """Here are some quotable characters in example paragraphs
First, a true example::
Begin & < >
Finally, embedded in a code segment '& < >'.
"""
expected_text = """
<h3>Here are some quotable characters in example paragraphs</h3>
<p> First, a true example:
<pre>
Begin & < >
</pre>
</p>
<p> Finally, embedded in a code segment '& < >'.</p>
"""
self._testConversion(
input_text,
'StructuredText',
'html',
expected_text,
'Converting ST to HTML with quotable characters did not produce expected results.',
)
|