[Doc-SIG] docstring grammar

[David Ascher]

On Tue, 30 Nov 1999, Mark Hammond wrote:

> * The [blah] notation is good, but needs to be well defined.  eg,
> "[module.function]" when used in the context of a package should use
> the same "module scoping" that Python itself uses.  However, the use
> of brackets may conflict with people who use inline code (rather than
> an example "block" - maybe something like "@" could be used?
> @module.function@ would be reasonable.

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 do *not* like
StructuredText's use of quotes to do inline code markup.

> * IMO, importing the module to extract this information is fine.  For
> the 1% of cases where it is not and the author of the module needs to
> use the tool, we could offer a hack - eg "sys.doc_building" will be
> defined when the tool is running, so could fine tune their code
> appropriately.  For the vast majority of cases, I guess that importing
> would be just fine and make the tool simpler, thereby giving more
> chance of it one day existing :-)  Indeed, do it the simple way, and
> the first person who needs the parse-only option can help code it :-)

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.

> * Example/test code should be clearly identifiable.  Tim Peters
> docstring tester could also be hacked to work with with format.

I need to go back and look at Tim's code again.

> Further, it should be possible to have lots of discrete sample code,
> each with their own discussion - eg:
> """
> The following code shows how to do this:
> Example:
>   def foo():
>     etc
> 
> /Example:
> The following code shows how to do that:
> Example:
>   def bar():
>     etc

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?

--david