[PYTHON DOC-SIG] Structured documentation syntax

[Robin Friedrich]

|> From: Ka-Ping Yee <s-ping@orange.cv.tottori-u.ac.jp>
|> To: Jim Fulton <jim.fulton@digicool.com>
|> Cc: doc-sig@python.org
|> Subject: Re: [PYTHON DOC-SIG] Structured documentation syntax
|> 
|> Hi again.  Given that the goal is to have a more flexible
|> syntax, i can understand now why you chose to allow three
|> kinds of list bullets, why it's better to leave double-quotes
|> visible, and why we might as well allow "1 Heading" or
|> "1. Heading" or "1.2 Heading" or "1.2. Heading".
|> 
|> Thank you for the explanations.
|> 
|> I was just expressing a personal preference about **emphasis**,
|> *emphasis*, and _emphasis_, but i don't feel as strongly
|> about that as Fredrik Lundh seems to.

Just to clarify. Gendoc uses *emphasis* and **strong** to delineate
text.  The underscores were rejected partly because they are harder to
segregate from normal Python names like __init__ which appear in doc
strings often.

|> 
|> Mostly, though, i do still feel that double-quotes aren't
|> really the best choice for hyperlinks (and i don't think
|> any existing doc strings contain hyperlinks, anyway).  Are
|> there typical uses of brackets, other than [references],
|> that i haven't thought of?

This is easy to change. I really didn't care, much I just picked
double quotes out of the air. [] & {} would have worked as well.
I have used this hyperlink feature in my doc strings and it works
fine.
|> 
|> Are there really many doc-strings already that use -- to
|> make definition lists?  I have seen very few definition-list
|> structures anywhere, and those i have seen use just ":".
|> I would prefer to avoid "--", but i guess i can live with it.

I use them whenever I list out the parameters of the function
and the public attributes.
Is this an esthetic thing only or do you wish to really reserve
it for emdash?

|> 
|> I'm looking through Grail source while thinking about this.
|> Noticed in a few places: maybe it would be safe to assume
|> that an identifier followed by () is a function name, and
|> thus treat it as <code> (and possibly hyperlink it)?
|> Specifically, this regex:
|> 
|>     [A-Za-z_]+(\.[A-Za-z_]+)*\(\)
|> 
|> using AWK syntax.
|> 
The gendoc approach is not to parse through the source files
(unless you use the -p option) at all. It lets python import
do that and then just walk through the symbol dictionaries to
collect doc strings. So no assumptions need to be made. In fact
gendoc does generate hyperlinks for other functions/modules.
See
http://www.python.org/sigs/web-sig/HTMLgen/html/index.html
|> 
|> I was glad to hear that there's a convention for function
|> documentation.  I was about to propose something specific.
|> To make the one-line description consistent in its form,
|> i was thinking of:
|> 
|>     nouns (classes, attributes, variables):
|>         Use an object phrase, e.g. "a can of spam"
|> 
|>     verbs (functions, methods):
|>         Use the imperative form, e.g. "Count to (exactly) three."
|>         Format as a complete sentence (capital and period).
|> 
|> > For Python functions there are function object attributes for
|> > getting function argument names and defaults.
|> 
|> Yes, but their descriptions would still be in the doc-string, right?

Well this is debateble by some but I agree with you on this.
|> 
|> > For more complex functions, I use somthing like:
|> > 
|> >   The arguments to this function are:
|> > 
|> >      foo  -- description of foo
|> > 
|> >      bar  -- description of bar
|> > 
|> >      def1 -- description of def1, including the default value
|> > 
|> >      def2 -- description of def2, including the default value
|> > 
|> > Note that this is very readable as text and will be converted to
|> > a nice descriptive list in HTML.  It would also be quite easy to write
|> > a function to find and extract the argument descriptions from the
|> > text, if necessary.
|> 
|> Yes, this stands out very nicely.  Can we agree to put such
|> a list immediately after the one-line description, if there
|> is to be one, and not worry about explicitly preceding it
|> with "the arguments are..." -- thus establishing the use of
|> a definition list in this position as a convention?

I think this convention may be too restrictive. Again, gendoc
detects def lists by their structure not their position. This could
be part of a style guide though.

-Robin

=================
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
=================