[Doc-SIG] Docstrings Format

[Mark Hammond]

> >     4. It must contain sufficient information so it can be converted
> >        to any reasonable markup format.
>
> I disagree with "4": I cannot mark up things like "this is a Python
> variable".

I am not with you here.  Whether you agree or not about (4) seems quite
independent of the capability to  add certain markups?

I agree with (4), but also agree with your requirement for that markup
capability.

> If you show me how to extend StructuredText for these
> kind of things, it would definitely get a chance.

I hate to tell you this Moshe, but I would speculate that the general
feeling on this SIG (assuming it hasnt changed over the last 12 months)
would be that StructuredText definitely has a chance regardless ;-)

> Please have a look at the PEP and see the exact markup goals
> I've outlined. Of course, if you do not agree with the goals,
> you can say that too...

I agree with the goals in general, but agree with Ken's new goal.  As a
nit-pick:
    3. It must not contain information which can be deduced from parsing
       the module.

maybe needs to be reworded slightly, as docstrings generally _do_ include
redundant information such as the function and parameter names, even though
these are obviously able to be deduced.

However, your PEP as it stands doesnt actually _say_ anything!  As the PEP
itself says, you have rehashed what as already been discussed ad-nauseam
right here.  Without a specific markup proposal it doesn't seem to add much
of value, and as soon as you try and extend it to a specific markup
proposal, we are back in the exact same position as 6 months ago.

I would vote that we explicitly state a goal is to use StructuredTextNG if
possible, and that the focus of the PEP then become two-fold:
* Identifying and fixing limitations in StructuredTextNG, as relevant to
Python docstrings.
* A specific, concrete markup proposal for Python docstrings (ie, narrow the
flexibility of StructuredTextNG to a reasonable subset for Python that
docstring tools can rely on.)

Pity-noone-asked-me-to-vote-though <winky> ly,

Mark.

Mark.