On 5/15/07, Charles R Harris <[EMAIL PROTECTED]> wrote:
On 5/15/07, Alan G Isaac <[EMAIL PROTECTED]> 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
_______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
