On Jan 22, 2008 12:56 PM, Charles R Harris <[EMAIL PROTECTED]> wrote: > > > > > On Jan 21, 2008 8:38 PM, Charles R Harris <[EMAIL PROTECTED]> wrote: > > > > > > > > > > On Jan 21, 2008 6:09 PM, Jarrod Millman <[EMAIL PROTECTED]> wrote: > > > > > > > > On Jan 21, 2008 2:03 PM, Matthew Brett <[EMAIL PROTECTED]> wrote: > > > > Search for the docstring standard, I hit this: > > > > > > > > http://www.scipy.org/DocstringStandard > > > > > > Good catch, I didn't know this page existed. If I recall correctly, > > > Keir Mierle showed up on the mailing list around the time we were > > > discussing the docstring standard. He proposed to do some work, but > > > then must have gotten busy with something else. In particular, I > > > believe he was interested in seeing a unified docstring standard for > > > numpy, scipy, and matplotlib. I guess he put this page up during that > > > period. I went ahead and deleted it, since it conflicts with the > > > official docstring standard. > > > > > > > > > > but I think the current thinking is this: > > > > > > > > http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines > > > > > > > > Is that correct? Does the first page apply to matplotlib in some way? > > > > Should we change the first page to match the second now? > > > > > > Yes. That page is autogenerated from the official coding standard > > > that is in the numpy trunk. One of the nice features of trac is that > > > it can render restructured text from the svn repository. This helps > > > us keep from having duplicate information that needs to be kept in > > > sync by hand. > > > > > > > > > If I hit the source code link in the generated html, it looks like that > page was generated from the old document format. The new document format > doesn't produce output that looks anything like that and epydoc generates a > couple of warnings: > > > > | File /home/charris/workspace/numpy/numpy/doc/example.py, line 19, in > > | example.foo > > | Warning: Line 24: Wrong underline character for heading. > > | Warning: Lines 27, 30, 32, 37, 39, 41, 43, 48, 50: Improper paragraph > > | indentation. > > > > > > The new document format requires a preprocessor that has yet to be > written. > > > > Since epydoc also works for compiled modules, I think the easiest way to do > that is to fork epydoc. The syntax of the new markup is context sensitive - > single types are no longer in {} - so parsing will be a bit more > complicated. As ReST is not part of the current document markup, we might > consider removing the parts of the document documentation that refer to it. > I must confess I don't get those discussion on docstring - at all. I think there has been some discussion on this for almost one year, and I have never managed to "compile" a full doc for numpy or scipy.
Nobody likes to write doc, specially if you have to follow many rules. Not being able to see the result does not help. I don't know much about the current documation tools situation with python, but I have seen good, automatically generated doc for python modules: for example, the current developement doc of python (http://docs.python.org/dev/) looks pretty good to me, and using the same tools as python makes more sense than forking our own, no ? Or am I missing something fundamental ? cheers, David _______________________________________________ Numpy-discussion mailing list [email protected] http://projects.scipy.org/mailman/listinfo/numpy-discussion
