On Tue, Jul 7, 2009 at 1:38 AM, Robert Cimrmancimr...@ntc.zcu.cz wrote:
Hi Ondrej,
Ondrej Certik wrote:
Hi,
it's very difficult for me to use the VTK writer, since it has no documentation about the input format:
""" def write( self, filename, mesh, out = None ):
fd = open( filename, 'w' ) fd.write( vtk_header % op.basename( sys.argv[0] ) ) """
Yes, the documentation is missing and this is bad.
this is very difficult to use. Robert, what do you think about using a similar scheme to document things like here:
I like sphinx, you know it :) It would be great to have a similar site for sfepy, too.
in particular, look for example here:
http://certik.github.com/python-theora/module_theora.html#theora.Theora.aspe...
how each method is documented. Basically the trick is that first you need to execute one script, that downloads test video files. Then you can access those files like:
t = Theora(test_files[2])
see the doctest. So in sfepy the simple script would first calculate some results and save it to probably vtk files (maybe others too).
There are already such result files - all it takes to get them is to use runTests.py - look into output-tests. Or, running simple.py with some of the examples in input/ is ok too.
Then you would test them in the doctests. Also I must say I quite like to always import everything in the docstring explicitly, because you can then just copy & paste it to a python session and it is guaranteed to work. (as opposed to assume that the current file is imported by default, because it's not clear to the user how to import it).
+1 for copy & pasteable docstrings. The problem with sfepy is that there are usually no docstrings at all, blame me.
I plan to get a similar thing working for hermes2d too soon.
I use github too, so let us setup the sphinx docs there.
As for the docstring format, I would like to use the same that numpy uses.
Ok, great, so we agree on everything. I'll try to set it up soon for hermes2d and sfepy too.
Ondrej