[Epydoc-commits] SF.net SVN: epydoc: [1572] trunk/epydoc/src/epydoc
Brought to you by:
edloper
From: <dva...@us...> - 2007-03-07 01:23:20
|
Revision: 1572 http://svn.sourceforge.net/epydoc/?rev=1572&view=rev Author: dvarrazzo Date: 2007-03-06 17:23:18 -0800 (Tue, 06 Mar 2007) Log Message: ----------- - All "free" Epydoc paragraphs are rendered in HTML into ``<p>``\ 's: removed the "HTML postprocessing" required to fix excessive spacing. - Added an ``inline`` attribute to `Ticket` and `Element`. Inline elements are similar tho HTMl ``<span>``; they are rendered in HTML without ``<p>``. Inline elements are, for instance: - list items (fields too); - docstring summaries; - HTML code simplified: no more ``<br><br>`` to accomodate for the lack of ``<p>``. This layout is more CSS-friendly. - Paragraphs vertical margins tweaked. - H3 top margin value set for cross browser consistency (IE and FF have different defaults). Modified Paths: -------------- trunk/epydoc/src/epydoc/docstringparser.py trunk/epydoc/src/epydoc/docwriter/html.py trunk/epydoc/src/epydoc/docwriter/html_css.py trunk/epydoc/src/epydoc/markup/epytext.py trunk/epydoc/src/epydoc/test/encoding.doctest trunk/epydoc/src/epydoc/test/epytext.doctest Modified: trunk/epydoc/src/epydoc/docstringparser.py =================================================================== --- trunk/epydoc/src/epydoc/docstringparser.py 2007-03-06 19:24:12 UTC (rev 1571) +++ trunk/epydoc/src/epydoc/docstringparser.py 2007-03-07 01:23:18 UTC (rev 1572) @@ -507,6 +507,7 @@ """A ParsedDocstring containing the text 'Returns'. This is used to construct summary descriptions for routines that have empty C{descr}, but non-empty C{return_descr}.""" +RETURN_PDS._tree.children[0].attribs['inline'] = True ###################################################################### #{ Field Processing Error Messages Modified: trunk/epydoc/src/epydoc/docwriter/html.py =================================================================== --- trunk/epydoc/src/epydoc/docwriter/html.py 2007-03-06 19:24:12 UTC (rev 1571) +++ trunk/epydoc/src/epydoc/docwriter/html.py 2007-03-07 01:23:18 UTC (rev 1572) @@ -739,11 +739,11 @@ out('<!-- ==================== %s ' % typ.upper() + 'DESCRIPTION ==================== -->\n') out('<h1 class="epydoc">%s %s</h1>' % (typ, shortname)) - out(self.pysrc_link(doc) + '<br /><br />\n') + out('<p class="nomargin-top">%s</p>\n' % self.pysrc_link(doc)) # If the module has a description, then list it. if doc.descr not in (None, UNKNOWN): - out(self.descr(doc, 2)+'<br /><br />\n\n') + out(self.descr(doc, 2)+'\n\n') # Write any standarad metadata (todo, author, etc.) if doc.metadata is not UNKNOWN and doc.metadata: @@ -830,7 +830,7 @@ out('<!-- ==================== %s ' % typ.upper() + 'DESCRIPTION ==================== -->\n') out('<h1 class="epydoc">%s %s</h1>' % (typ, shortname)) - out(self.pysrc_link(doc) + '<br /><br />\n') + out('<p class="nomargin-top">%s</p>\n' % self.pysrc_link(doc)) if ((doc.bases not in (UNKNOWN, None) and len(doc.bases) > 0) or (doc.subclasses not in (UNKNOWN,None) and len(doc.subclasses)>0)): @@ -864,7 +864,7 @@ # If the class has a description, then list it. if doc.descr not in (None, UNKNOWN): - out(self.descr(doc, 2)+'<br /><br />\n\n') + out(self.descr(doc, 2)+'\n\n') # Write any standarad metadata (todo, author, etc.) if doc.metadata is not UNKNOWN and doc.metadata: Modified: trunk/epydoc/src/epydoc/docwriter/html_css.py =================================================================== --- trunk/epydoc/src/epydoc/docwriter/html_css.py 2007-03-06 19:24:12 UTC (rev 1571) +++ trunk/epydoc/src/epydoc/docwriter/html_css.py 2007-03-07 01:23:18 UTC (rev 1572) @@ -60,6 +60,7 @@ * defined below). */ body { background: $body_bg; color: $body_fg; } +p { margin-top: 0.5em; margin-bottom: 0.5em; } a:link { color: $body_link; } a:visited { color: $body_visited_link; } dt { font-weight: bold; } @@ -84,7 +85,8 @@ */ h1.epydoc { margin: 0; font-size: +140%; font-weight: bold; } h2.epydoc { font-size: +130%; font-weight: bold; } -h3.epydoc { font-size: +115%; font-weight: bold; } +h3.epydoc { font-size: +115%; font-weight: bold; + margin-top: 0.2em; } td h3.epydoc { font-size: +115%; font-weight: bold; margin-bottom: 0; } table.navbar { background: $navbar_bg; color: $navbar_fg; Modified: trunk/epydoc/src/epydoc/markup/epytext.py =================================================================== --- trunk/epydoc/src/epydoc/markup/epytext.py 2007-03-06 19:24:12 UTC (rev 1571) +++ trunk/epydoc/src/epydoc/markup/epytext.py 2007-03-07 01:23:18 UTC (rev 1572) @@ -367,6 +367,8 @@ if para_token.indent == indent_stack[-1]: # Colorize the paragraph and add it. para = _colorize(doc, para_token, errors) + if para_token.inline: + para.attribs['inline'] = True stack[-1].children.append(para) else: estr = "Improper paragraph indentation." @@ -554,6 +556,11 @@ heading; C{None}, otherwise. Valid heading levels are 0, 1, and 2. + @type inline: C{bool} + @ivar inline: If True, the element is an inline level element, comparable + to an HTML C{<span>} tag. Else, it is a block level element, comparable + to an HTML C{<div>}. + @type PARA: C{string} @cvar PARA: The C{tag} value for paragraph C{Token}s. @type LBLOCK: C{string} @@ -574,7 +581,8 @@ HEADING = "heading" BULLET = "bullet" - def __init__(self, tag, startline, contents, indent, level=None): + def __init__(self, tag, startline, contents, indent, level=None, + inline=False): """ Create a new C{Token}. @@ -591,12 +599,15 @@ @param level: The heading-level of this C{Token} if it is a heading; C{None}, otherwise. @type level: C{int} or C{None} + @param inline: Is this C{Token} inline as a C{<span>}?. + @type inline: C{bool} """ self.tag = tag self.startline = startline self.contents = contents self.indent = indent self.level = level + self.inline = inline def __repr__(self): """ @@ -794,14 +805,16 @@ linenum += 1 # Add the bullet token. - tokens.append(Token(Token.BULLET, start, bcontents, bullet_indent)) + tokens.append(Token(Token.BULLET, start, bcontents, bullet_indent, + inline=True)) # Add the paragraph token. pcontents = ([lines[start][para_start:].strip()] + [line.strip() for line in lines[start+1:linenum]]) pcontents = ' '.join(pcontents).strip() if pcontents: - tokens.append(Token(Token.PARA, start, pcontents, para_indent)) + tokens.append(Token(Token.PARA, start, pcontents, para_indent, + inline=True)) # Return the linenum after the paragraph token ends. return linenum @@ -1768,25 +1781,14 @@ indent+2, seclevel) for c in tree.children] - # Get rid of unnecessary <P>...</P> tags; they introduce extra - # space on most browsers that we don't want. - for i in range(len(variables)-1): - if (not isinstance(tree.children[i], basestring) and - tree.children[i].tag == 'para' and - (isinstance(tree.children[i+1], basestring) or - tree.children[i+1].tag != 'para')): - variables[i] = ' '*(indent+2)+variables[i][5+indent:-5]+'\n' - if (tree.children and - not isinstance(tree.children[-1], basestring) and - tree.children[-1].tag == 'para'): - variables[-1] = ' '*(indent+2)+variables[-1][5+indent:-5]+'\n' - # Construct the HTML string for the variables. childstr = ''.join(variables) # Perform the approriate action for the DOM tree type. if tree.tag == 'para': - return wordwrap('<p>%s</p>' % childstr, indent) + return wordwrap( + (tree.attribs.get('inline') and '%s' or '<p>%s</p>') % childstr, + indent) elif tree.tag == 'code': style = tree.attribs.get('style') if style: @@ -2002,7 +2004,7 @@ # Extract the first sentence. parachildren = variables[0].children - para = Element('para') + para = Element('para', inline=True) doc.children.append(para) for parachild in parachildren: if isinstance(parachild, basestring): Modified: trunk/epydoc/src/epydoc/test/encoding.doctest =================================================================== --- trunk/epydoc/src/epydoc/test/encoding.doctest 2007-03-06 19:24:12 UTC (rev 1571) +++ trunk/epydoc/src/epydoc/test/encoding.doctest 2007-03-07 01:23:18 UTC (rev 1572) @@ -27,27 +27,27 @@ >>> testencoding('''# -*- coding: cp874 -*- ... """abc ABC 123 \x80 \x85""" ... ''') - abc ABC 123 € … + <p>abc ABC 123 € …</p> >>> testencoding('''# -*- coding: cp1250 -*- ... """abc ABC 123 \x80 \x82 \x84 \x85 \xff""" ... ''') - abc ABC 123 € ‚ „ … ˙ + <p>abc ABC 123 € ‚ „ … ˙</p> >>> testencoding('''# -*- coding: cp1251 -*- ... """abc ABC 123 \x80 \x81 \x82 \xff""" ... ''') - abc ABC 123 Ђ Ѓ ‚ я + <p>abc ABC 123 Ђ Ѓ ‚ я</p> >>> testencoding('''# -*- coding: cp1252 -*- ... """abc ABC 123 \x80 \x82 \x83 \xff""" ... ''') - abc ABC 123 € ‚ ƒ ÿ + <p>abc ABC 123 € ‚ ƒ ÿ</p> >>> testencoding('''# -*- coding: cp1253 -*- ... """abc ABC 123 \x80 \x82 \x83 \xfe""" ... ''') - abc ABC 123 € ‚ ƒ ώ + <p>abc ABC 123 € ‚ ƒ ώ</p> Unicode tests: @@ -71,52 +71,52 @@ <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> >>> # UTF-8 with a BOM & a coding directive: >>> testencoding(utf8_bom+"# -*- coding: utf-8 -*-\n"+utf8_test) <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> >>> # UTF-8 with a BOM & no coding directive: >>> testencoding(utf8_bom+utf8_test) <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> Tests for KOI8-R: >>> testencoding('''# -*- coding: koi8-r -*- ... """abc ABC 123 \x80 \x82 \x83 \xff""" ... ''') - abc ABC 123 ─ ┌ ┐ Ъ + <p>abc ABC 123 ─ ┌ ┐ Ъ</p> Tests for 'coding' directive on the second line: >>> testencoding('''\n# -*- coding: cp1252 -*- ... """abc ABC 123 \x80 \x82 \x83 \xff""" ... ''') - abc ABC 123 € ‚ ƒ ÿ + <p>abc ABC 123 € ‚ ƒ ÿ</p> >>> testencoding('''# comment on the first line.\n# -*- coding: cp1252 -*- ... """abc ABC 123 \x80 \x82 \x83 \xff""" ... ''') - abc ABC 123 € ‚ ƒ ÿ + <p>abc ABC 123 € ‚ ƒ ÿ</p> >>> testencoding("\n# -*- coding: utf-8 -*-\n"+utf8_test) <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> >>> testencoding("# comment\n# -*- coding: utf-8 -*-\n"+utf8_test) <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> Tests for shift-jis @@ -132,12 +132,12 @@ >>> testencoding('''# -*- coding: utf-8 -*- ... """abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80""" ... ''') - abc ABC 123 € ߿ ࠀ + <p>abc ABC 123 € ߿ ࠀ</p> >>> testencoding('''# -*- coding: utf-8 -*- ... u"""abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80""" ... ''') - abc ABC 123 € ߿ ࠀ + <p>abc ABC 123 € ߿ ࠀ</p> Under special circumstances, we may not be able to tell what the proper encoding for a docstring is. This happens if: @@ -166,33 +166,33 @@ <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> >>> testencoding(utf8_bom+"# -*- coding: utf-8 -*-\n"+utf8_test, introspect=False) <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> >>> testencoding(utf8_bom+utf8_test, introspect=False) <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> >>> testencoding("# -*- coding: utf-8 -*-\n"+utf8_test, parse=False) <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> >>> testencoding(utf8_bom+"# -*- coding: utf-8 -*-\n"+utf8_test, parse=False) <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> >>> testencoding(utf8_bom+utf8_test, parse=False) <p>abc ABC 123</p> <p>0x80-0x7ff range: €  ߾ ߿</p> <p>0x800-0xffff range: ࠀ ࠁ  </p> - 0x10000-0x10ffff range: 𐀀 𐀁   + <p>0x10000-0x10ffff range: 𐀀 𐀁  </p> Context checks ============== @@ -219,12 +219,12 @@ ... ''') abc ABC 123 € ߿ ࠀ abc ABC 123 € ߿ ࠀ + <p>abc ABC 123 € ߿ ࠀ</p> abc ABC 123 € ߿ ࠀ abc ABC 123 € ߿ ࠀ abc ABC 123 € ߿ ࠀ abc ABC 123 € ߿ ࠀ abc ABC 123 € ߿ ࠀ - abc ABC 123 € ߿ ࠀ >>> testencoding('''# -*- coding: utf-8 -*- ... class A: @@ -238,11 +238,11 @@ ... z = property(doc=u"abc ABC 123 \xc2\x80 \xdf\xbf \xe0\xa0\x80") ... ''') abc ABC 123 € ߿ ࠀ + <p>abc ABC 123 € ߿ ࠀ</p> abc ABC 123 € ߿ ࠀ abc ABC 123 € ߿ ࠀ abc ABC 123 € ߿ ࠀ abc ABC 123 € ߿ ࠀ - abc ABC 123 € ߿ ࠀ Modified: trunk/epydoc/src/epydoc/test/epytext.doctest =================================================================== --- trunk/epydoc/src/epydoc/test/epytext.doctest 2007-03-06 19:24:12 UTC (rev 1571) +++ trunk/epydoc/src/epydoc/test/epytext.doctest 2007-03-07 01:23:18 UTC (rev 1572) @@ -45,14 +45,14 @@ ... @foo: This is a field.""") <para>This is a paragraph.</para> <fieldlist><field><tag>foo</tag> - <para>This is a field.</para></field></fieldlist> + <para inline=True>This is a field.</para></field></fieldlist> >>> print testparse(""" ... This is a paragraph. ... @foo: This is a field.""") <para>This is a paragraph.</para> <fieldlist><field><tag>foo</tag> - <para>This is a field.</para></field></fieldlist> + <para inline=True>This is a field.</para></field></fieldlist> >>> print testparse(""" ... This is a paragraph. @@ -60,23 +60,23 @@ ... Hello.""") <para>This is a paragraph.</para> <fieldlist><field><tag>foo</tag> - <para>This is a field. Hello.</para></field></fieldlist> - + <para inline=True>This is a field. Hello.</para></field> + </fieldlist> >>> print testparse("""Paragraph\n@foo: field""") <para>Paragraph</para> <fieldlist><field><tag>foo</tag> - <para>field</para></field></fieldlist> + <para inline=True>field</para></field></fieldlist> >>> print testparse("""Paragraph\n\n@foo: field""") <para>Paragraph</para> <fieldlist><field><tag>foo</tag> - <para>field</para></field></fieldlist> + <para inline=True>field</para></field></fieldlist> >>> print testparse("""\nParagraph\n@foo: field""") <para>Paragraph</para> <fieldlist><field><tag>foo</tag> - <para>field</para></field></fieldlist> + <para inline=True>field</para></field></fieldlist> Make sure thta unindented lists are not allowed: @@ -122,20 +122,22 @@ >>> print testparse("""Paragraph\n- list item""") <para>Paragraph</para> - <ulist><li><para>list item</para></li></ulist> + <ulist><li><para inline=True>list item</para></li></ulist> Make sure that indented lists are allowed: >>> print testparse('This is a paragraph.\n - This is a list item.\n'+ ... 'This is a paragraph') <para>This is a paragraph.</para> - <ulist><li><para>This is a list item.</para></li></ulist> + <ulist><li><para inline=True>This is a list item.</para></li> + </ulist> <para>This is a paragraph</para> >>> print testparse('This is a paragraph.\n\n - This is a list item.'+ ... '\n\nThis is a paragraph') <para>This is a paragraph.</para> - <ulist><li><para>This is a list item.</para></li></ulist> + <ulist><li><para inline=True>This is a list item.</para></li> + </ulist> <para>This is a paragraph</para> >>> print testparse(""" @@ -145,7 +147,8 @@ ... ... This is a paragraph""") <para>This is a paragraph.</para> - <ulist><li><para>This is a list item.</para></li></ulist> + <ulist><li><para inline=True>This is a list item.</para></li> + </ulist> <para>This is a paragraph</para> >>> print testparse(""" @@ -154,18 +157,22 @@ ... - This is a list item. ... This is a paragraph""") <para>This is a paragraph.</para> - <ulist><li><para>This is a list item.</para></li></ulist> + <ulist><li><para inline=True>This is a list item.</para></li> + </ulist> <para>This is a paragraph</para> >>> print testparse(""" ... - This is a list item.""") - <ulist><li><para>This is a list item.</para></li></ulist> + <ulist><li><para inline=True>This is a list item.</para></li> + </ulist> >>> print testparse("""- This is a list item.""") - <ulist><li><para>This is a list item.</para></li></ulist> + <ulist><li><para inline=True>This is a list item.</para></li> + </ulist> >>> print testparse("""\n- This is a list item.""") - <ulist><li><para>This is a list item.</para></li></ulist> + <ulist><li><para inline=True>This is a list item.</para></li> + </ulist> Basic list tests: @@ -176,10 +183,10 @@ >>> LI3 = " - This is a list\n item." >>> LI4 = "\n - This is a list\n item." >>> PARA = ('<para>This is a paragraph.</para>') - >>> ONELIST = ('<ulist><li><para>This is a '+ + >>> ONELIST = ('<ulist><li><para inline=True>This is a '+ ... 'list item.</para></li></ulist>') - >>> TWOLIST = ('<ulist><li><para>This is a '+ - ... 'list item.</para></li><li><para>This is a '+ + >>> TWOLIST = ('<ulist><li><para inline=True>This is a '+ + ... 'list item.</para></li><li><para inline=True>This is a '+ ... 'list item.</para></li></ulist>') >>> for p in (P1, P2): @@ -198,7 +205,7 @@ ... PARA+TWOLIST+PARA) >>> LI5 = " - This is a list item.\n\n It contains two paragraphs." - >>> LI5LIST = ('<ulist><li><para>This is a list item.</para>'+ + >>> LI5LIST = ('<ulist><li><para inline=True>This is a list item.</para>'+ ... '<para>It contains two paragraphs.</para></li></ulist>') >>> checkparse(LI5, LI5LIST) >>> checkparse('%s\n%s' % (P1, LI5), PARA+LI5LIST) @@ -206,7 +213,7 @@ >>> LI6 = (" - This is a list item with a literal block::\n" + ... " hello\n there") - >>> LI6LIST = ('<ulist><li><para>This is a list item with a literal '+ + >>> LI6LIST = ('<ulist><li><para inline=True>This is a list item with a literal '+ ... 'block:</para><literalblock> hello\n there'+ ... '</literalblock></li></ulist>') >>> checkparse(LI6, LI6LIST) @@ -216,10 +223,10 @@ Item wrap tests: >>> LI = "- This is a list\n item." - >>> ONELIST = ('<ulist><li><para>This is a '+ + >>> ONELIST = ('<ulist><li><para inline=True>This is a '+ ... 'list item.</para></li></ulist>') - >>> TWOLIST = ('<ulist><li><para>This is a '+ - ... 'list item.</para></li><li><para>This is a '+ + >>> TWOLIST = ('<ulist><li><para inline=True>This is a '+ + ... 'list item.</para></li><li><para inline=True>This is a '+ ... 'list item.</para></li></ulist>') >>> for indent in ('', ' '): ... for nl1 in ('', '\n'): @@ -229,7 +236,7 @@ Summary ======= -The implementation of the summaization function works as expected. +The implementation of the summarization function works as expected. >>> from epydoc.markup import epytext >>> def getsummary(s): @@ -298,14 +305,14 @@ ... return (v or '').rstrip() >>> print epytext2html("{1:{2:3}}") -{1:{2:3}} +<p>{1:{2:3}}</p> >>> print epytext2html("C{{1:{2:3}}}") -<code>{1:{2:3}}</code> +<p><code>{1:{2:3}}</code></p> >>> print epytext2html("{1:C{{2:3}}}") -{1:<code>{2:3}</code>} +<p>{1:<code>{2:3}</code>}</p> >>> print epytext2html("{{{}{}}{}}") -{{{}{}}{}} +<p>{{{}{}}{}}</p> >>> print epytext2html("{{E{lb}E{lb}E{lb}}}") -{{{{{}} +<p>{{{{{}}</p> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |