list formatting - need blank lines?
Brought to you by:
doughellmann,
krlosaqp
Menu
▾
▴
HappyDoc refers to the structured text rules in
http://www.python.org/sigs/doc-sig/stext.html
This document states:
------------------
A paragraph that begins with a '-', '*', 'o' is treated as an unordered list(bullet) element. (Note: In list paragraphs it is not necessary to serparate each item with a blank line.)
-------------
However, when I try to edit a python program that
contains the text
- array
- zeros
it doesn't format as two separate bullet items.
Somewhere else in that document it will say something to the effect that paragraphs are separated by at least one blank line. Each entry in a list is considered to be its own paragraph, so (as you suspect) you need a blank line between each one.
Seems like a silly standard to require blank lines between list elements. Makes the comment take a lot of space in the code (not to mention looking odd). Personally, I think javadoc's nicer. Oh well, gotta work with what you've got, I suppose.
Feel free to write a javadoc docstring converter. :-)
I chose StructuredText because it was in fairly wide use and allows for reasonable markup without a lot of extra junk that looks bad when you're looking at docstrings interactively. Newer versions of ST have different rules. The reST project (hosted here on SourceForge) eliminates the requirement for blank lines. The last time I looked there was no way to convert reST to HTML, though, and I have enough other features to add that I don't have time to write that. When something becomes available, reST will be an option for those who want to use it. I haven't decided yet if it will be the default formatting scheme.
Doug
I wasn't meaning to criticize HappyDoc - of course, it makes sense to use whatever standard is in place, and since Python guidelines say to use StructuredText, it's no doubt best to use that. But still, it would be nice without the spaces. =)