Exception when arguments are bulleted

[rob-smallshire]

Original author: austin.bingham (June 26, 2012 18:25:42)

With a docstring like this:

def foo(): '''Something.

Args:
  * arg1: an argument
'''

hieroglyph will throw an exception.

Original issue: http://code.google.com/p/cartouche/issues/detail?id=1

[rob-smallshire]

From robert.smallshire@gmail.com on June 27, 2012 18:02:21 I'm in three minds how to solve this one.

The first approach is to modify the parser so that this bulleted syntax is accepted silently. In essence, it would become a completely acceptable syntax form for Cartouche, albeit one that goes beyond the informally specified Google syntax.

The second approach is to modify the parser to accept the bullet syntax as above, but to issue an advisory warning.

The third option is to issue a warning and to skip processing of the whole docstring. The unprocessed docstring will be passed through to Sphinx.

As ever, error recovery in parsers is difficult and I don't think it's worthwhile to attempt processing with the remainder of the docstring.

[rob-smallshire]

From robert.smallshire@gmail.com on June 27, 2012 19:18:00 Patch to implement option (1) above attached. Still not convinced this is the right approach.

[rob-smallshire]

From austin.bingham on June 28, 2012 07:50:45 The patch seems to work just fine. This same problem exists for exceptions specifications: bulleted entried in the "Raises:" section need to be treated the same as arguments. (edit: bulleted exceptions seemed broken at first, but now they seem to work...mysteries.)

My arguments for supporting this syntax are (in bullet form, of course):

• It may be found in existing code bases, so cartouche will be easier to use if it accepts the bullets. Liberal on input, strict on output.
• My editor deals with the bullets better, it seems. It knows about indentation and stuff when they're present. Granted, I could probably make it understand google-style, but I'm lazy.
• I personally find it easier to read the bulleted form. That may just be habit, but that's the way it is.

If you want to emit a warning (optionally?) when you encounter this syntax, that's fine with me.

If you ultimately decide to not support this syntax, I'd really appreciate better diagnostics. As it is, each cartouche failures turn into bug hunts, and that's pretty lame.

[rob-smallshire]

From robert.smallshire@gmail.com on June 29, 2012 06:49:16 Better diagnostics are certainly required throughout.

I think I might go with a fourth option, which is to have this syntax supported by cartouche, but disabled by default. I would make an optional available which could be enabled in conf.py.

[rob-smallshire]

From robert.smallshire@gmail.com on June 29, 2012 20:17:42 This issue is fixed by changelist cc63a876a994 and prior commits.

Both the Args and Raises blocks now optionally support bulleted lists using any of the standard reStructuredText bullet characters. To enable support for these behaviours in your documentation add the following to your conf.py:

-- Options for cartouche --------------------------------------------

cartouche_accept_bulleted_args = True cartouche_accept_bulleted_raises = True