[Numpy-discussion] Documentation

[Charles R Harris]

On 5/15/07, Gary Ruben <gruben at bigpond.net.au> wrote:
>
> Hi Charles,
>
> In you post, is your numpy/doc reference referring to the file
> HOWTO_DOCUMENT.txt?
>
> I notice that this is not the same as the one here
> <http://scipy.org/DocstringStandard>
> which I think may be the preferred standard. If someone can confirm
> this, it should probably replace the HOWTO_DOCUMENT.txt content. IMO,
> the wiki version is more readable and also more comprehensive.


Yes, I started with the HOWTO_DOCUMENT.txt in numpy.

Hmm, the scipy version does look better, but I have some nits:

1) The standard text width for almost everything software is 79, one less
then the old standard terminal width and the number of columns in an IBM
5081 punch card. The proposed standard should adhere to this and require the
right margin to be set at 79 independently of everything else. Requiring
different right hand margins in different sections is *ridiculous*, no
sensible coder would adhere to such a standard, let the software worry about
it.

2) Lining up the paragraph indentations after a list item heading is a job
for nematodes. I suggest using the standard restructured text definition
lists. Example:

List Heading:

    label1
        explanation

    label2
        explanation

This will look decent when run through the current epydoc. You can put
dashes after the labels for type markup, or even colons as long as the
explanation isn't proceeded by a blank line.

3) I think the main headings look better when italicized, so surround them
with stars thusly: *Heading*

4) I introduced a new section, "Description", because when epydoc formats
the documentation it serves to separate the main description from the short
one line summary. It can also serve as a tag if we write our own preparser.

To summarize, the documentation standard should be the simplest thing that
looks good both in a terminal and when formatted into pdf or html by epydoc.
The scipy standard strikes me a far too convoluted and downright ugly in a
terminal.

Chuck
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20070515/c1a1822b/attachment.html>