Travis, A few questions. 1) I can't find any systematic code testing units, although there seem to be tests for regressions and such. Is there a place we should be putting such tests? 2) Any plans for code documentation? I documented some of my stuff with doxygen markups and wonder if we should include a Doxyfile as part of the package. 3) Would you consider breaking out the Converters into a separate .c file for inclusion? The code generator seems to take care of the ordering. Chuck
On Thursday 21 September 2006 09:05, Charles R Harris wrote:
Travis,
A few questions.
1) I can't find any systematic code testing units, although there seem to be tests for regressions and such. Is there a place we should be putting such tests?
2) Any plans for code documentation? I documented some of my stuff with doxygen markups and wonder if we should include a Doxyfile as part of the package.
Are able to use doxygen for Python code ? I thought it only worked for C (and alike) ?
3) Would you consider breaking out the Converters into a separate .c file for inclusion? The code generator seems to take care of the ordering.
Chuck
Travis,
A few questions.
1) I can't find any systematic code testing units, although there seem to be tests for regressions and such. Is there a place we should be putting such tests? All tests are placed under the tests directory of the corresponding sub-package. They will only be picked up by .test(level < 10) if the file is named test_<module_name>. .test(level>10) should pick up all test files. If you want to name something different but still have it run at a test level < 10, then you need to run the test from one of the other test files that will be picked up (test_regression.py and test_unicode.py are doing that for example).
2) Any plans for code documentation? I documented some of my stuff with doxygen markups and wonder if we should include a Doxyfile as part of the package. I'm not familiar with Doxygen, but would welcome any improvements to the code documentation.
3) Would you consider breaking out the Converters into a separate .c file for inclusion? The code generator seems to take care of the ordering. You are right that it doesn't matter which order the API subroutines are
Charles R Harris wrote: placed. I'm not opposed to more breaking up of the .c files, as long as it is clear where things will be located. The #include strategy is necessary to get it all in one Python module, but having smaller .c files usually makes for faster editing. It's the arrayobject.c file that is "too-large" IMHO, however. That's where I would look for ways to break it up. The iterobject and the data-type object could be taken out, for example. -Travis
Are able to use doxygen for Python code ? I thought it only worked for C (and alike) ?
There is an ugly-hack :) http://i31www.ira.uka.de/~baas/pydoxy/ But I wouldn't recommend using it, rather stick with Epydoc. -- Louis Cordier <lcordier@point45.com> cell: +27721472305 Point45 Entertainment (Pty) Ltd. http://www.point45.org
On 9/21/06, Sebastian Haase <haase@msg.ucsf.edu> wrote:
Travis,
A few questions.
1) I can't find any systematic code testing units, although there seem to be tests for regressions and such. Is there a place we should be putting such tests?
2) Any plans for code documentation? I documented some of my stuff with doxygen markups and wonder if we should include a Doxyfile as part of
On Thursday 21 September 2006 09:05, Charles R Harris wrote: the
package.
Are able to use doxygen for Python code ? I thought it only worked for C (and alike) ?
IIRC correctly, it now does Python too. Let's see... here is an example ## Documentation for this module. # # More details. ## Documentation for a function. # # More details. def func(): pass Looks like ## replaces the /** Chuck
Are able to use doxygen for Python code ? I thought it only worked for C (and alike) ?
IIRC correctly, it now does Python too. Let's see... here is an example ## Documentation for this module. # # More details.
## Documentation for a function. # # More details. def func(): pass Looks like ## replaces the /**
I never found it (although I haven't looked too hard), but I always thought there was an official way to document python code -- minimally to put the documentation in the docstring following the function definition: def func(..): """One liner. Continue docs -- some type of reStructredText style """ pas Isn't that the same docstring that ipython uses to bring up help, when you do: In [1]: myobject.some_func? So .. I guess I'm wondering why we want to break from the standard? -steve
On Thu, 21 Sep 2006 10:05:58 -0600 "Charles R Harris" <charlesr.harris@gmail.com> wrote:
Travis,
A few questions.
1) I can't find any systematic code testing units, although there seem to be tests for regressions and such. Is there a place we should be putting such tests?
2) Any plans for code documentation? I documented some of my stuff with doxygen markups and wonder if we should include a Doxyfile as part of the package.
We don't have much of a defined standard for docs. Personally, I wouldn't use doxygen: what I've seen for Python versions are hacks, whose output looks like C++, and which requires markup that's not like commonly-used conventions in Python (\brief, for instance). Foremost for Python doc strings, I think, is that it look ok when using pydoc or similar (ipython's ?, for instance). That means a minimal amount of markup. Someone previously mentioned including cross-references; I think that's a good idea. A 'See also' line, for instance. Examples are good too, especially if there's been disputes on the interpretation of the command :-) For the C code, documentation is autogenerated from the /** ... API */ comments that determine which functions are part of the C API. This are put into files multiarray_api.txt and ufunc_api.txt (in the include/ directory). The files are in reST format, so the comments should/could be. At some point I've got to through and add more :-) -- |>|\/|< /--------------------------------------------------------------------------\ |David M. Cooke http://arbutus.physics.mcmaster.ca/dmc/ |cookedm@physics.mcmaster.ca
Steve Lianoglou wrote:
So .. I guess I'm wondering why we want to break from the standard?
We don't as far as Python code goes. The code that Chuck added Doxygen-style comments to was C code. I presume he was simply answering Sebastian's question rather than suggesting we use Doxygen for Python code, too. -- 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
Hi, On 9/21/06, Robert Kern <robert.kern@gmail.com> wrote:
Steve Lianoglou wrote:
So .. I guess I'm wondering why we want to break from the standard?
We don't as far as Python code goes. The code that Chuck added Doxygen-style comments to was C code. I presume he was simply answering Sebastian's question rather than suggesting we use Doxygen for Python code, too.
Exactly. I also don't think the Python hack description applies to doxygen any longer. As to the oddness of \param or @param, here is an example from Epydoc using Epytext @type m: number @param m: The slope of the line. @type b: number @param b: The y intercept of the line. The X{y intercept} of a Looks like they borrowed something there ;) The main advantage of epydoc vs doxygen seems to be that you can use the markup inside the normal python docstring without having to make a separate comment block. Or would that be a disadvantage? Then again, I've been thinking of moving the python function docstrings into the add_newdocs.py file so everything is together in one spot and that would separate the Python docstrings from the functions anyway. I'll fool around with doxygen a bit and see what it does. The C code is the code that most needs documentation in any case. Chuck
On Thu, 21 Sep 2006, Charles R Harris apparently wrote:
As to the oddness of \param or @param, here is an example from Epydoc using Epytext @type m: number @param m: The slope of the line. @type b: number @param b: The y intercept of the line.
Compare to definition list style for consolidated field lists in section 5.1 of http://epydoc.sourceforge.net/fields.html#rst which is much more elegant, IMO. Cheers, Alan Isaac
On Thu, 21 Sep 2006, "David M. Cooke" apparently wrote:
Foremost for Python doc strings, I think, is that it look ok when using pydoc or similar (ipython's ?, for instance). That means a minimal amount of markup.
IMO reStructuredText is very natural for documentation, and it is nicely handled by epydoc. fwiw, Alan Isaac
participants (8)
-
Alan G Isaac
-
Charles R Harris
-
David M. Cooke
-
Louis Cordier
-
Robert Kern
-
Sebastian Haase
-
Steve Lianoglou
-
Travis Oliphant