[Doc-SIG] docstring grammar

[Mark Hammond]

> I personally would prefer to keep [] for references and
> introduce @..@ (or
> some other delimiter) for inline code, mostly because [] is
> so common in
> journals as a way of indicating bibliographic references.  I

Fair enough.

> I see.  So the workaround for those scripts which can't be
> imported is to
> start them with:
>
> import sys; if sys.doc_building: sys.exit()
>
> Not too bad.

I more had in mind:

if sys.doc_building:
  # Normally critical we do this.
  dont_do_something_really_expensive()

We dont need to execute the bulk of the code, just import the module
and get a few of the symbols.

> That would be written (with the current proposal):
>
>   The following code shows how to do this:
>     Example:
>       def foo():
>         etc
>
>   The following code shows how to do that:
>     Example:
>       def bar():
>         etc
>
> Is that ok w/ you?

Perfect.

Mark.