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

Edward D. Loper edloper@gradient.cis.upenn.edu
Wed, 28 Mar 2001 10:55:35 EST

So, I was thinking about how to make ST more formal, more like a real
markup language, and possibly more lightweight.. And that led me to
think about what I *really* want in a markup language for docstrings..
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
  6. Sections
  7. Hierarchical sections
  8. The ability to mark a word as emphasized
  9. URLs
 10. The ability to mark regions as emphasized
 11. The ability to mark regions as strong
 12. Footnotes/endnotes
 13. Internal anchors/references to parts of a docstring

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?