Hi, Search for the docstring standard, I hit this: http://www.scipy.org/DocstringStandard 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? Matthew
On Jan 21, 2008 2:03 PM, Matthew Brett <matthew.brett@gmail.com> wrote:
Search for the docstring standard, I hit this:
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. Thanks, -- Jarrod Millman Computational Infrastructure for Research Labs 10 Giannini Hall, UC Berkeley phone: 510.643.4014 http://cirl.berkeley.edu/
On Jan 21, 2008 6:09 PM, Jarrod Millman <millman@berkeley.edu> wrote:
On Jan 21, 2008 2:03 PM, Matthew Brett <matthew.brett@gmail.com> wrote:
Search for the docstring standard, I hit this:
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. Chuck
On Jan 21, 2008 8:38 PM, Charles R Harris <charlesr.harris@gmail.com> wrote:
On Jan 21, 2008 6:09 PM, Jarrod Millman <millman@berkeley.edu> wrote:
On Jan 21, 2008 2:03 PM, Matthew Brett <matthew.brett@gmail.com> wrote:
Search for the docstring standard, I hit this:
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. Chuck
On Jan 22, 2008 12:56 PM, Charles R Harris <charlesr.harris@gmail.com> wrote:
On Jan 21, 2008 8:38 PM, Charles R Harris <charlesr.harris@gmail.com> wrote:
On Jan 21, 2008 6:09 PM, Jarrod Millman <millman@berkeley.edu> wrote:
On Jan 21, 2008 2:03 PM, Matthew Brett <matthew.brett@gmail.com> wrote:
Search for the docstring standard, I hit this:
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
David Cournapeau wrote:
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 ?
Yes. Sphinx does not do automatically generated documentation. -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
On Jan 21, 2008 7:56 PM, Charles R Harris <charlesr.harris@gmail.com> wrote:
If I hit the source code link in the generated html, it looks like that
On Jan 21, 2008 8:38 PM, Charles R Harris <charlesr.harris@gmail.com> wrote: 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.
Hey Chuck, I am sorry that there has been so much confusion over the docstring standards. As you know, the problems you are pointing out arose from the changes Travis made in December. I added a warning to the top of the coding style guideline explaining the situation: http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines Once Travis writes a tool to render the docstrings, we can go ahead and update the instructions. Thanks, -- Jarrod Millman Computational Infrastructure for Research Labs 10 Giannini Hall, UC Berkeley phone: 510.643.4014 http://cirl.berkeley.edu/
On Jan 22, 2008 3:18 PM, Jarrod Millman <millman@berkeley.edu> wrote:
On Jan 21, 2008 7:56 PM, Charles R Harris <charlesr.harris@gmail.com> wrote:
If I hit the source code link in the generated html, it looks like that
On Jan 21, 2008 8:38 PM, Charles R Harris <charlesr.harris@gmail.com> wrote: 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.
Hey Chuck,
I am sorry that there has been so much confusion over the docstring standards. As you know, the problems you are pointing out arose from the changes Travis made in December. I added a warning to the top of the coding style guideline explaining the situation: http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines Once Travis writes a tool to render the docstrings, we can go ahead and update the instructions.
Thanks for the update in svn. It makes the current situation much clearer, I think. cheers, David
Charles R Harris wrote:
On Jan 21, 2008 6:09 PM, Jarrod Millman <millman@berkeley.edu <mailto:millman@berkeley.edu>> wrote:
On Jan 21, 2008 2:03 PM, Matthew Brett <matthew.brett@gmail.com <mailto:matthew.brett@gmail.com>> 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 <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.
epydoc from SVN works just fine once the following line is added at the top. __docformat__ = "restructuredtext en" -- Robert Kern "I have come to believe that the whole world is an enigma, a harmless enigma that is made terrible by our own mad attempt to interpret it as though it had an underlying truth." -- Umberto Eco
On Jan 21, 2008 11:27 PM, Robert Kern <robert.kern@gmail.com> wrote:
Charles R Harris wrote:
On Jan 21, 2008 6:09 PM, Jarrod Millman <millman@berkeley.edu <mailto:millman@berkeley.edu>> wrote:
On Jan 21, 2008 2:03 PM, Matthew Brett <matthew.brett@gmail.com <mailto:matthew.brett@gmail.com>> 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 <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.
epydoc from SVN works just fine once the following line is added at the top.
__docformat__ = "restructuredtext en"
So it does, sorry for the noise. Does it work with the docstrings for the C code also? Chuck
Am Dienstag, 22. Januar 2008 07:27:19 schrieb Robert Kern:
The new document format requires a preprocessor that has yet to be written.
epydoc from SVN works just fine once the following line is added at the top.
__docformat__ = "restructuredtext en"
No need to clutter the files, just use "epydoc --docformat restructuredtext" Ciao, / / /--/ / / ANS
participants (6)
-
Charles R Harris -
David Cournapeau -
Hans Meine -
Jarrod Millman -
Matthew Brett -
Robert Kern