[Doc-SIG] suggestions for a PEP

[Edward D. Loper]

Tibs wrote:

>> 	1. Decide on STpy (or an ST variant), with minimal
>> 	   extensions
>> 	2. Produce an application that parses it
>> 	3. Get it accepted, and get people using it
>> 	4. THEN, once we've changed the culture, spring
>> 	   our wonderful scheme for semi-formal markup
>> 	   on them, that allows them to extract special
>> 	   information.

What do you mean by semi-formal markup?  If it's just fields (i.e.,
global structure markup) then somewhere around 2, I would also add:
    * Tell people what the semi-formal markup scheme will most
      likely look like, but say that it's not implemented yet.
That way, people can add semi-formal markup, and when it gets
implemented, they magically get prettier outputs.

If you mean coloring (i.e., local structure markup), then I'd
say definitely leave it for later. :)

>> a. I don't actually believe that you are going to get most Python
>> programmers to DO semi-formal markup for you. I *do* believe there's a
>> good chance we'll get many people to write at least a little human
>> readable text. So guess what I'm after...

I think that a bunch of programmers would be willing to do global
markup (special places to describe arguments, etc).  I don't think
they would do formal coloring markup..

>>    http://www.tibsnjoan.co.uk/STpy.html#taggedparas
>>    which describes things like::
>> 
>> 	Author: Guido van Rossum
>> 
>>    and::
>> 
>> 	Arguments:
>> 	   fred -- this is a useless name for an argument

I agree with the idea, but I strongly think that things like author
should be description list items.  Advantages:
  * it requires no changes to current STpy
  * it's more compatible with other STs
  * it seems conceptually "cleaner"
  * we don't need to give special meaning to yet another 
    character (":")
  * it's *much* easier to describe a general mechanism, so
    other people can extend it for their own tools.
  * if they do something wrong, (e.g., put unordered list items
    below "Arguments:"), then we can just format it like normal
    ST. (and give a warning, if we're nice)

Problems will come up with your formalism with lines like:

  Author: Mr. bob frank    # does the . mean it's a got a sentence?
  Things to do: eat, sleep # how does this get treated?

Unless you can come up with a compelling reason for using::

  Author: Guido

instead of::

  Author -- Guido

I think we should go with the latter.

>>  And although it says there that
>> it should be left for second phase implementation, the start of support
>> is already in docutils.

I think it will be helpful to people if we can get this streight now.
That way, they can use it while documenting code in the interim
period.  But it shouldn't get in the way of getting everything else
done, if we can't manage to figure it out now.

>> erm - sorry? if you want your inline docs to be available to a browser
>> (and I *do*) then they've pretty well got to be around somewhere!

(I assume) he means he doesn't want things like __author__ and 
__version__ at the top level of a module.

>> dosctrings inherit like any other value, surely?
Um.. yes, but that's not always what you want.  Basically, if I define::

  class A:
     def f(x):
        "this if f(x)"
        return 1
     
  class B(A): 
     def f(x):
        return 2

Then I might want B.f to inherit its docs from A.f.  This would be 
especially nice for things like UserList, so my classes will have
docs for its methods without me having to duplicate explanations.

But in a sense, this is a tool issue..  Although, it will affect
whether people tend to copy comments for overriden functions..

-Edward