#16 Docstrings are not html-quoted

feature request
formatter (18)

For example, the following snipped of code:

def __init__(self, file, **keyw):
"""Construct a File object.

<file> is a string holding a filename.


results in HTML for which "<file>" is passed through as "<file>" without quoting of the <>, resulting in the whole word being invisible in the browser. It should instead be "<file>", I think.


  • Doug Hellmann

    Doug Hellmann - 2001-01-21
    • milestone: 102142 --> feature request
  • Doug Hellmann

    Doug Hellmann - 2001-02-10
    • assigned_to: nobody --> doughellmann
    • status: open --> closed-invalid
  • Doug Hellmann

    Doug Hellmann - 2001-02-10

    I've bounced back and forth on this. For now, I'm going to leave it as it is. I might be convinced to do something different in the future, but the most likely thing I'll do is add an option to the formatter to allow the user to control the behavior to their liking.

    The idea, though, is that you would write your docstrings using StructureText. You might change your example, then, to look like:

    def __init__(self, file, **keyw):
    """Construct a File object.

    file -- A string holding a filename.


  • Michael Haggerty

    Let me try to bounce you back again :-)

    It is true that my example could be rewritten to eliminate the need for angle backets. If you like you can try to force me to change this aspect of how I like to document things.

    But that is missing the big picture. If I understand correctly, happydoc obfuscates even perfectly reasonable and awkward-to-avoid formulations, like "The input parameters must satisfy x<y<z".

    What is the argument *against* running users' text strings through the equivalent of html_quote()? The only persuasive argument would be if you want to let users include their own HTML in comments, like """This function rearranges the tree structure; see <img src="tree-doc.png> for details.""" Is this your goal? Maybe it's a worth goal, but it has a substantial cost: people now have to do html-quoting manually in their docstrings, producing docstrings that are less legible in the source code. It seems to me that goes against the spirit of StructureText.


Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:

No, thanks