Charles R Harris wrote:
On Dec 29, 2007 7:59 PM, Fernando Perez <fperez.net@gmail.com mailto:fperez.net@gmail.com> wrote:
On Dec 29, 2007 6:51 PM, Charles R Harris <charlesr.harris@gmail.com <mailto:charlesr.harris@gmail.com>> wrote: > If not, we should > definitely decide on the structure of the docstrings and stick to it. +100I 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.