[PYTHON DOC-SIG] Structured documentation syntax

[Jim Fulton]

Ka-Ping Yee wrote:
> 
> Hi -- i just saw the following on python-list:
> 
> > Daniel Larsson has released gendoc 0.6 for your documentation
> > pleasure. The big change here is the adoption of structured text
> > for the doc string formatting standard.
> 
> -- and went to have a look at the doc-sig page to find out
> what the formatting syntax was.
> 
> Syntactic things:
> -----------------
> 
> I know that it may not be my place to speak so soon, as i have
> not spent any time researching what has been done, but a look
> at the description on the doc-sig page produced these thoughts
> (in order of decreasing strength):
> 
>   - Double-quotes seem too common to be used as hyperlink delimiters.
>     More in keeping with common practice might be the use of [],
>     the way most people use them to mark references.
> 
>   - Also, it would make sense for double and single quotes to both
>     mark example code.  What if you need to talk about a single-quoted
>     string, for example?

You can always use double-quoted strings, rather than single-quoted
strings to show string literals.  Using *only* single-quoted strings
for examples leaves the option of using double quoted strings for
string literals in examples.

> 
>   - As noted on the page, use of "--" is reasonably common for
>     em-dashes (in fact, i'd even suggest turning them into real
>     &emdash; entities in HTML).  Why not use "::" instead for
>     tagged list elements?
> 
>   - Couldn't you just choose one bullet marker for list elements,
>     instead of three?

The goal of this effort is to be able to use unprocessed doc strings.
It us often useful, when reading the raw text to have a 
visual distinction between different types of bullets.
 
Also, there are many conventions for typing bullets and there's no harm 
in trying to support most or all of them.

I'd like structured text to be as unrestrictive as possible so that
people writing doc strings don't have to thing hard about formatting.

>   - Is it true that a first-level list begins "12 First sentence..."
>     but deeper levels begin "3.4. First sentence..."?  That is, the
>     description on the page seems to imply that the periods follow
>     each ordering component, rather than separate them.

Right.  You can also use: '1. First sentance'
 
>   - It might be nicer (simpler) to use _underscores_ for italics
>     and use *single asterisks* for bold.  (Special Python names
>     that start and end with underscores should be marked as code
>     examples anyway...)

Actually, *spam* is used for emphasis, not italics.  It just happens
that most browsers use italics for emphasis.  Personally, I don't
like how _underscores_ looks.  I would never type a text document
that way.  I would have no problem with having single asterisks
indicate strong, rather than emphasized.
 
> Btw, how do you make headings?  Do you just make everything a
> sub-paragraph of a short paragraph containing the heading?

Single-line paragraphs with sub-paragraphs are treated as headings.

> Semantic things:
> ----------------
> 
> Has there been any thought towards a well-defined standard
> for documenting functions?  I'm thinking of things about
> the interface, like parameter lists and descriptions of
> parameters, and maybe a defined place for a one-sentence
> (or even one-predicate) summary of what the function does,
> and/or what circumstances it expects to be run under.

The first line of the doc string provides a short description
of the function (or any other documented object).  This is your
one-sentance description.

For Python functions there are function object attributes for getting
function argument names and defaults.

For built-in (C, C++, Fortran, etc.) functions, there is an 
agreed-upon convention for including signatures (argument 
names and defaults) in the one-line summary, like this:

  spam(foo,bar,[def1,def2]) -- Summary of spam

Everything above is standard, although perhaps not well known. 
:-)

For argument descriptions, I like and follow the example of 
the Python library manual, which includes argument descriptions
in the prose of the full descriptions, at least for simple
functions whose doc strings are only a paragraph or two.

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.

Jim

-- 
Jim Fulton         Digital Creations
jim@digicool.com   540.371.6909
## Python is my favorite language ##
##     http://www.python.org/     ##

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

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