[PYTHON DOC-SIG] Structured documentation syntax

[Ka-Ping Yee]

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.

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?

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'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.


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?

> 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?


Ping

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

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