[Numpy-discussion] Documentation

[Charles R Harris]

On 5/15/07, Charles R Harris <charlesr.harris at gmail.com> wrote:
>
>
>
> On 5/15/07, Alan G Isaac <aisaac at american.edu> wrote:
> >
> > > Gary Ruben wrote:
> > >> 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.
> >
> >
> > On Tue, 15 May 2007, Robert Kern apparently wrote:
> > > Note that despite the title, we haven't actually agreed to this
> > format. It was
> > > simply a proposal.
> >
> >
> > Just to add a bit more specificity, I believe that the
> > HOWTO_DOCUMENT.txt document at
> > http://svn.scipy.org/svn/numpy/trunk/numpy/doc/HOWTO_DOCUMENT.txt
> > summarizes a substantial discussion and broad agreement.
> > I.e., it is currently the preferred standard.
> >
> > Apologies if I missed a relevant discussion,
>
>
>
> I think the output generated for the consolidated lists is too ugly to
> bear. The bullets are distracting, there is no spacing between entries, and
> the explanatory text is appended on the same line, making it difficult to
> read. So get rid of ":Parameters:" and just use "Parameters: ". Futhermore,
> the dashes under Notes and Examples make these section headers and PyDoc
> moves these blocks to the top so that they are printed before the Parameters
> list  and other list blocks. Did no one actually run this stuff through
> PyDoc? So my recommendations are to remove the leading :'s from the list
> headings, making them definition lists, italicize them, and insert the
> mandatory blank line after. Then remove the dashes  from under Notes and
> Examples, and let the documenter choose between lists with the appended : ,
> or just indent the text after, which has the same effect if there are no
> list item headings, which there typically aren't in those sections.
>
> Chuck
>

s/PyDoc/epydoc/g
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20070515/1b90d469/attachment.html>