[Numpy-discussion] [SciPy-dev] Doc-day
Travis E. Oliphant
Sat Dec 29 23:52:43 CST 2007
Charles R Harris wrote:
> On Dec 29, 2007 7:59 PM, Fernando Perez <email@example.com
> <mailto:firstname.lastname@example.org>> wrote:
> On Dec 29, 2007 6:51 PM, Charles R Harris
> <email@example.com <mailto:firstname.lastname@example.org>> wrote:
> > If not, we should
> > definitely decide on the structure of the docstrings and stick
> to it.
> 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.
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
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.
More information about the Numpy-discussion