[Doc-SIG] What's important in a docstring markup language?

[Tony J Ibbs (Tibs)]

Edward D. Loper wrote:
> The following is an ordered list of the features I think it should
> have.  I.e., I think features earlier on the list are more important,
> and ones later are less important.  I would personally be happy
> to draw a line anywhere after 4, and forget about anything under
> the line. :)
>
>   1. The ability to distinguish text that can be rendered with soft
>      spaces and word wrapped from text that should be rendered in
>      monospace with whitespace preserved (i.e., the ability to
>      distinguish natural language from everything else).
>      This includes both inline literals and literal blocks
>   2. The ability to label the semantic content of parts of
>      descriptions, eg., as the return value or as a description
>      of an argument.
>   3. The ability to properly handle doctest blocks (this is a high
>      priority, because these have become standard)
>   4. Unordered lists
>   5. Ordered lists

I think those are in my top six as well.

>   6. Sections

In docstrings, which are typically short, I think these are at the end
of the list

>   7. Hierarchical sections

Almost no need for these in docstrings, and I think 2 (or at worst 3)
levels is more than enough

>   8. The ability to mark a word as emphasized

I don't want 8 at all, I want 10.

>   9. URLs

Quite important if this is meant to be "joined up" documentation (to use
a horrible buzz phrase our politicians seem addicted to). It is very
important to be able to reference documentation elsewhere, and having
them "clickable" in derived formats that support that ability is
important too.

>  10. The ability to mark regions as emphasized

See above. I would place this in my top half a dozen.

>  11. The ability to mark regions as strong

Don't care - in docstrings, I think one form of emphasis is enough (ref
fat.html)

>  12. Footnotes/endnotes

Useful, very useful, but not essential

>  13. Internal anchors/references to parts of a docstring

A frill, a frippery, something to forget until someone comes up with a
use case.

> Does this correspond more-or-less with other people's priorities?
> What markup do people feel is essential for documenting the APIs of
> python objects?

So I guess my list is:

1. "plain" text versus "literal" text (as you say, inline and by the
block)
2. "Python" inline versus "other literal" inline.
3. Emphasis (so I don't have to SHOUT A LOT)
4. doctest blocks, 'cos they're easy and useful
5. Lists - all three types - I use all three a lot
6. Label blocks (those things like "Arguments" and so on, which contain
a particular sort of information)

Those six are my core. Their order isn't too important, 'cos I want all
of them (I guess 6 is slightly less important)

7. URI detection

This lives by itself, and nearly makes the "prime" list.

8. Footnotes/endnotes
9. Headers and sections

I'm not sure about the order of those last two.

Mind you, I think this is a useful excercise (with luck, it won't tell
us anything new, of course!).

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)