[Numpy-discussion] Documentation

[Gary Ruben]

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.

Gary R.


Charles R Harris wrote:
> Hi All,
> 
> I've been trying out epydoc to see how things look. Apart from all the 
> error messages, it does run. However, I didn't like the appearance of 
> the documentation structured as suggested in numpy/doc, either in the 
> terminal or in the generated html. In particular, I didn't like the 
> consolidated lists and the interpreted variable names. I can see where 
> these might be useful down the road, but for now I stuck to definition 
> lists with italicized headings and plain old variable names.
> 
> Another problem we might want to address are the doctest blocks. Numpy 
> inserts blank lines when it is printing out multidimensional arrays and 
> because blank lines indicate the end of the block that screws up the 
> formatting. It would also be nice to make the SeeAlso entries links to 
> relevant functions.
> 
> Anyway, I've attached the html file generated from fromnumeric.py for 
> your flamage and suggestions. The routines I restructured are sort, 
> argsort, searchsorted, diagonal, std, var, and mean.
> 
> Chuck