[PYTHON DOC-SIG] Structured documentation syntax

[Ka-Ping Yee]

Robin Friedrich wrote:
> 
> 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.

Sure.  I follow your reasons.
 
> 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.

Okay.  My vote is for [].

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

Primarily i'm concerned about emdash, i'd say.  It's not a big deal,
but *if* there's still time to choose, i'd like to choose well.

> |> 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
[...]
> The gendoc approach is not to parse through the source files
> (unless you use the -p option) at all.

Yeah, i saw that.  I'm talking about making this assumption
when someone talks about another function *within* the __doc__
string, though -- as part of parsing __doc__.

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

I'm not suggesting that def lists be only allowed to appear
immediately after the one-liner.  I agree that def lists
should be allowed anywhere, detected only by structure --
my suggestion is that we form a convention to reserve the
position of "right after the one-liner" for the one
particular def list which *describes the arguments*.

This way, it is possible to ask for the description of a
particular argument and to automatically find and return it
with confidence.


Ping

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

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