#54 html output from reStructuredText cluttered with paragraphs

devel (cvs)
closed-fixed
Edward Loper
5
2006-03-17
2005-03-06
Daniele Varrazzo
No

reST docstrings are translated into HTML with too many
<P>s.

Internally, each docstring <field_body> tag contain a
<paragraph> child: this child is converted into an html
<P>paragraph</P>, so parameters description and
types are split from surrounding text.

Tested with epydoc v. 2.1 and CVS HEAD on 2005-03-06

Example: the function:

def read_fields(cnn, table):
"""Populate the table fields.

:param cnn: open cursor to the database
:param table: table to be populated
:type cnn: `string`
:type table: `Table`
:rtype: `None`
"""
pass

results in html looking like:

<begin html appearance>
[...]
Parameters:
cnn -
open cursor to the database

(type=
string

)
table -
table to be populated

(type=
Table

)
Returns:
None
<end html appearance>

A similar docstring in epytext correctly returns a more
compact html representation:

<begin html appearance>
[...]
Parameters:
cnn - open cursor to the database
(type=string)
table - table to be populated
(type=Table)
Returns:
None
<end html appearance>

Discussion

  • Logged In: YES
    user_id=1053920

    Did anybody find the same problem?

    Anyway, here is a patch against
    epydoc/markup/restructuredtext.py v. 2.1 resolving the issue
    for me.

     
  • Logged In: YES
    user_id=1053920

    In the previous patch, some of the buggy fields were not
    patched. Here they are.

     
  • Proposed patch against 1157711 bug

     
    Attachments
  • Eric Huss
    Eric Huss
    2005-05-29

    Logged In: YES
    user_id=393416

    There are some additional fields that appear to be missing.

    I think 'keyword' should be added.

    Also, for reasons I don't know, the return tagname is 'Return'
    with a capital R so that it does not match.

    I'm concerned that maintaining this list may by bug-prone in
    the future. I know that docutils 0.3.5 did not exhibit this
    problem. I sent an email to epydoc-devel a while back about
    this problem. I'm wondering if epydoc could potentially use
    objects that will cause should_be_compact_paragraph to
    return True instead of cleaning up after-the-fact.

    Below is my original post:

    We've noticed a problem when using epydoc with the latest
    version of docutils. The HTML output is including <p> tags
    around the content making it look, well, wrong.

    I have some output examples that show this here:
    http://www.ehuss.org/epydoc/

    The change seems to be centered around CVS version 1.132
    (or maybe 1.139?) of docutils/writers/html4css1.py which
    altered the behavior of determining if something should be
    a "compact paragraph". This change was made in
    November. Thus docutils 0.3.5 works, but 0.3.7 does not.

    We think that epydoc should not pass things to docutils that
    are documents (because of the
    should_be_compact_paragraph method in html4css1 is
    checking for that), but we are entirely unsure of what should
    be done to fix this (if, perhaps, it is a problem with docutils).
    Has anyone else seen this, or know anything more about it?

     
  • Logged In: YES
    user_id=1053920

    I made some tests and i think the list may be dropped:
    simply filtering away the paragraph from the first element
    of the list produces good results. If a field contains more
    paragraphs (maybe a discursive "todo" or "bug") results are
    neither bad.

     
  • Logged In: YES
    user_id=1053920

    Mmm... actually modified fields interfere with summary
    generation. In summaries the first sentence is extraced from
    a probably longer piece of documentation. Usually it comes
    from the bulk of the docstring (for classes methods etc.)
    but this can be done for variables which don't have a
    docstring. So they are documented by a field in another
    object's docstring.

    The fields involved in summary should be: var, ivar, cvar.
    All other fields have the paragraph stripped away.

    Please let me know if you report missing pieces of
    documentation or wrong output. The patch is in the CVS.

     
  •  
    Attachments
  • Edward Loper
    Edward Loper
    2006-03-17

    • status: open --> closed-fixed
     
  • Edward Loper
    Edward Loper
    2006-03-17

    Logged In: YES
    user_id=195958

    Fixed in cvs/svn