[Numpy-discussion] [SciPy-dev] Doc-day

Travis E. Oliphant oliphant at enthought.com
Sun Dec 30 00:52:43 EST 2007


Charles R Harris wrote:
>
>
> On Dec 29, 2007 7:59 PM, Fernando Perez <fperez.net at gmail.com 
> <mailto:fperez.net at gmail.com>> wrote:
>
>     On Dec 29, 2007 6:51 PM, Charles R Harris
>     <charlesr.harris at gmail.com <mailto:charlesr.harris at gmail.com>> wrote:
>
>     > If not, we should
>     > definitely decide on the structure of the docstrings and stick
>     to it.
>
>     +100
>
>  
> I have raised the topic of documentation formats on the list several 
> times, and the discussions have always petered out. So I made a 
> decision, posted what *worked* with epydoc, and also generated a 
> significant amount of documentation. Now that is tossed out with 
> hardly a mention. I would like to propose that anyone who submits a 
> new documentation standard also submit code to parse the result, 
> compare it to the existing practice, discuss why it is an 
> improvement, and generate documentation to show how it works. I did 
> all of those things, I expect nothing less from others if we are going 
> to reinvent the wheel. And the end result should be available as soon 
> the the formatting changes are made, not at some indefinite point in 
> the future.

Hey Chuck,

I'm the guilty party in the docstring revisions, and I'm very sorry that 
my actions seemed to undermine your contributions (which are very much 
appreciated).

The changes to the docstring format that I pushed are not much different 
from what was put in place.  However, they make it so that the 
documentation standard for SciPy and NumPy is not different from the ETS 
standard.  In addition, I think it conserves horizontal real-estate and 
looks better when just printed as plain text (which is mostly how 
docstrings get read).  

I ran epydoc (on the example.py file) and it still produces output that 
is very readable even if it is not currently as good looking as the 
previously rendered result.   A relatively simple pre-processer should 
be able to produce fancier output with epydoc.

As we were going to have a Doc-Day, and several people were going to be 
adding documentation, I wanted to cement the docstring standard and I 
did not want it to be based on a "technological" reason (i.e. we have 
all this stuff in the docstring so that epydoc can produce pretty 
output).    My experience is that >90% of docstring-reading is done in 
plain-text, so this should drive the decision, and not the availability 
of a tool to render it.

We had to cement a decision, so I did it.  I am very sorry for stepping 
on your toes.  I should have looked at who committed the most recent 
changes to the documentation information pages and taken more time to 
work things out with you privately (but it was very early in the morning 
on Friday (2-4 am ish).   I also did not want to have another 
mailing-list discussion on docstring formats because as you've 
witnessed, it is not usually helpful on something which is primarily in 
the eye of the beholder.

I'll take responsibility to get something in place to render the 
docstrings more beautifully.  If anybody is interested in helping with 
that, please let me know.

Sheepishly yours,

-Travis O.






More information about the NumPy-Discussion mailing list