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] ) )
"""
this is very difficult to use. Robert, what do you think about using a similar scheme to document things like here:
http://certik.github.com/python-theora/
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). 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).
I plan to get a similar thing working for hermes2d too soon.
Ondrej
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.
r.
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
Ondrej Certik wrote:
Ok, great, so we agree on everything. I'll try to set it up soon for hermes2d and sfepy too.
That would be great, thanks! I assume you would set it up on your github site, and I would then pulled it to mine, right? All I need is the first barebone version of sphinx docs running. Then we can add the docstrings as time permits.
r.
On Wed, Jul 8, 2009 at 2:11 AM, Robert Cimrmancimr...@ntc.zcu.cz wrote:
Ondrej Certik wrote: > Ok, great, so we agree on everything. I'll try to set it up soon for
hermes2d and sfepy too.
That would be great, thanks! I assume you would set it up on your github site, and I would then pulled it to mine, right? All I need is the first barebone version of sphinx docs running. Then we can add the docstrings as time permits.
I'll first set it up for hermes2d, because I still need to fix some cython stuff to doctest well too (had some problems with that the last time). Then I will do the same for sfepy and post a branch for you to merge.
It may take me couple days to do so though.
Ondrej
Ondrej Certik wrote:
On Wed, Jul 8, 2009 at 2:11 AM, Robert Cimrmancimr...@ntc.zcu.cz wrote:
Ondrej Certik wrote:
Ok, great, so we agree on everything. I'll try to set it up soon for hermes2d and sfepy too. That would be great, thanks! I assume you would set it up on your github site, and I would then pulled it to mine, right? All I need is the first barebone version of sphinx docs running. Then we can add the docstrings as time permits.
I'll first set it up for hermes2d, because I still need to fix some cython stuff to doctest well too (had some problems with that the last time). Then I will do the same for sfepy and post a branch for you to merge.
It may take me couple days to do so though.
No problem at all, I will have first time to take care of it next week.
r.
participants (2)
-
Ondrej Certik
-
Robert Cimrman