#278 Improper paragraph indentation warning when it shouldn't

[Gabriel Rossetti]

Hello,

in mixed numbering types, like for example :

"""
Calling this will generate tick events. The events are generated in reverse order :

1. Tick-day event, if applicable
2. Tick-hour event, if applicable
3. Tick-minute event, if applicable
4. Tick event, if applicable

by applicable, it is ment that :

a. The reason for raising the event has come to be (I{e.g.} a whole tick-day has just lapsed)
b. A callback has been set for the event

@note: all applicable events will be raised
"""

it reports improper indention, when it shouldn't since the lower numbering is a new numbering and not a continuation of the previous. As you can see, in between the two I unindented to show the separation.

Also, it reports the same error when I align text broken into two lines because it was too long, like so :

"""
Blabla :

1. bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla.
2. bli bli bli bli bli bli bli bli bli bli bli bli
bli bli bli bli bli bli bli bli bli .
3. blo blo blo blo blo blo blo blo blo blo blo blo
blo blo blo blo blo blo.
"""

it wants me to do this :

"""
Blabla :

1. bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla.
2. bli bli bli bli bli bli bli bli bli bli bli bli
bli bli bli bli bli bli bli bli bli .
3. blo blo blo blo blo blo blo blo blo blo blo blo
blo blo blo blo blo blo.
"""

which I understand from a parser point of view, but when a person reads the source code (not the generated api), I think it "hides" the numbering.

Thanks,
Gabriel

[Edward Loper]

Logged In: YES
user_id=195958
Originator: NO

Numbered lists in epytext must start with numbers -- it does not support "a, b, c" or "i, ii, iii, iv" type ordered lists. See the epytext manual (section 2.2):

http://epydoc.sourceforge.net/epytext.html

As for indenting the contents of a bulleted list item (your second point), epydoc is perfectly happy dealing with this. Again, see the examples in section 2.2 of the manual. If you're getting a markup error from your first "Blabla" docstring, then let me know what it is; but when I run epydoc using that docstring, I get no errors.

Epytext is intentionally a very simple and conservative markup language. This is a design choice, because it means that it can be used as the default markup language, and will generally do the right thing even for docstrings that are not explicitly written using any markup language. In particular, it is conservative about detecting cases when it might not know how to format the text, and in those cases, it falls back to displaying the text as a fixed-width preformatted block. This is necessary, e.g., to allow me to run epydoc on the python stdlib and not end up misformatting some docstrings.

If you want a more flexible & powerful markup language, I recommend you look into using restructuredtext. See:

http://epydoc.sourceforge.net/manual-othermarkup.html

-Edward