Hi,
the Git version now contains a lot of interesting changes and new features compared to the latest released version (2009.3), see the would-be RELEASE_NOTES below. There are still some problems to be addressed, though, listed here:
Known problems:
- undocumented new features:
- 'functions' keyword and change to materials definition
- new application option 'use_equations' to select equations
- homogenization is completely undocumented
- chunk_size must be greater than the number of elements (-> 1 chunk only) for the "materials in physical QPs" to work properly
- isfepy is broken for multiple view() calls!
- sfepy_gui.py not updated for new Viewer capabilities (animations etc.)
- is the installation within femhub ok?? (Viewer changed a lot...)
While I will try to fix the problems before releasing, I am not sure we shall wait till all of them are fixed, what do you think?
I would also appreciate some help, apart from the usual testing. While there is probably nobody familiar enough with the internals (or am I wrong?), the topic accessible to some of you is the documentation, namely the 'functions' keyword and change to materials definition - if you feel like fixing this at [1], go ahead, please.
I would also like to set-up a sphinx-based documentation site for sfepy, like [2] or [3], probably using github. Any volunteers out there? I have made some attempts to learn how to do it, but have currently no time to go on. And yes, new functions added to sfepy are documented and use the sphinx-compatible format, following the numpy's standards.
[1] http://code.google.com/p/sfepy/wiki/ProblemDescription [2] http://docs.scipy.org/doc/ [3] http://docs.sympy.org/
Feel free to ask anything related to the features described below.
Yours truly, r.
Would-be RELEASE_NOTES:
- major branches merged:
- 'ulf' branch: updated Lagrangian (UL) formulation
- 'functions' branch:
- unified passing extra arguments to boundary condition, material, and region functions
- physical quadrature point generation
- unified/improved handling of material parameters in terms:
- all material parameters defined in physical quadrature points
- all terms updated, some terms were coalesced into one
- 'porous' branch: homogenized porous media
- input file keywords:
- new 'functions' keyword
- simplifications & unifications:
- results of all time steps of an evolutionary problem can be saved to a single HDF5 file
- enable passing variables data to ProblemDefinition.solve()
- runTests.py: allow multiple test files as command line arguments
- Viewer.call_mlab() split and refactored
- short syntax for periodic boundary conditions
- simplified input file syntax of materials
- postprocessing and visualization:
- using FileSource class abstracts the particular format for storing results:
- VTK, HDF5 supported now
- support for file sequences (evolutionary simulations)
- time step selection for HDF5 (single) and VTK (sequence) files
- animations (using ffmpeg)
- minimalistic ViewerGUI
- show scalar bars
- watch results file (HDF5) and add time steps as they are saved
- listing data ranges works offscreen, summary for file sequence
- sfepy_gui.py: Mayavi2-based GUI to launch simulations
- using FileSource class abstracts the particular format for storing results:
- changes aimed at interactive work:
- Domain, Region, Field creation refactoring
- data probing - postprocessing mode:
- read a previously probed data from the probe text file, re-plot them, and integrate them along the probe
- graphical logging:
- dynamic adding of data groups (new axes) to Log and ProcessPlotter
- many bug fixes, namely:
- fix import_file() for multiple imports
- miscellaneous updates:
- quasistatic time stepping
- new zero-order elements: 3_4_P0, 3_8_Q0
- more elastic tensor construction functions:
- elastic tensor from Young's modulus and Poisson's ratio
- elastic tensors for use in mixed formulation
- setting of parameter variables by a user-defined function
- new terms:
- dw_volume_wdot_scalar_eth (exponential decay dot product convolution term)
- dw_biot_eth (exponential decay Biot convolution term)
- dw_lin_elastic_eth (exponential decay elastic convolution term)
- updated Lagrangian (UL) formulation terms:
- dw_ul_bulk_penalty, dw_ul_he_neohook, dw_ul_he_mooney_rivlin
Hi Robert,
On Fri, Oct 9, 2009 at 9:01 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
I would also appreciate some help, apart from the usual testing. While there is probably nobody familiar enough with the internals (or am I wrong?), the topic accessible to some of you is the documentation, namely the 'functions' keyword and change to materials definition - if you feel like fixing this at [1], go ahead, please.
I updated the materials definition with the examples from issue #93 and added a section for the functions keyword. Hopefully it makes sense! :)
I would also like to set-up a sphinx-based documentation site for sfepy, like [2] or [3], probably using github. Any volunteers out there? I have made some attempts to learn how to do it, but have currently no time to go on. And yes, new functions added to sfepy are documented and use the sphinx-compatible format, following the numpy's standards.
If no one else wants to volunteer, I can look into this. It would be good to get someone with more experience with github/Sphinx to give some starting pointers.
[1] http://code.google.com/p/sfepy/wiki/ProblemDescription
Best, Logan
Hi Logan,
Quoting Logan Sorenson logan.s...@gmail.com:
Hi Robert,
On Fri, Oct 9, 2009 at 9:01 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
I would also appreciate some help, apart from the usual testing. While there is probably nobody familiar enough with the internals (or am I wrong?), the topic accessible to some of you is the documentation, namely the 'functions' keyword and change to materials definition - if you feel like fixing this at [1], go ahead, please.
I updated the materials definition with the examples from issue #93 and added a section for the functions keyword. Hopefully it makes sense! :)
It makes a perfect sense, thanks! :)
I think we should setup also a page where users could post their
examples/applications. Something like what we do at sfepy.kme.zcu.cz
site, but open for everybody.
I would also like to set-up a sphinx-based documentation site for sfepy, like [2] or [3], probably using github. Any volunteers out there? I have made some attempts to learn how to do it, but have currently no time to go on. And yes, new functions added to sfepy are documented and use the sphinx-compatible format, following the numpy's standards.
If no one else wants to volunteer, I can look into this. It would be good to get someone with more experience with github/Sphinx to give some starting pointers.
This is how numpy guys do it:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_BUILD_DOCS.txt
I have also some advice from Ondrej, I will post it here on Monday, as
I that information is on my workplace computer only...
[1] http://code.google.com/p/sfepy/wiki/ProblemDescription
cheers, r.
Hi Robert,
I think we should setup also a page where users could post their examples/applications. Something like what we do at sfepy.kme.zcu.cz site, but open for everybody.
This is a really good idea. Since that page looks like it runs on moinmoin, do you think it's possible to simply copy it over to another host and then open it up for everyone? Does anyone know if github supports moinmoin?
I would also like to set-up a sphinx-based documentation site for sfepy, like [2] or [3], probably using github. Any volunteers out there? I have made some attempts to learn how to do it, but have currently no time to go on. And yes, new functions added to sfepy are documented and use the sphinx-compatible format, following the numpy's standards.
If no one else wants to volunteer, I can look into this. It would be good to get someone with more experience with github/Sphinx to give some starting pointers.
This is how numpy guys do it:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_BUILD_DOCS.txt
I looked a bit into github. I was able to setup a repository on github fairly easy, so hosting the docs is no problem on there. But I'm not sure how to do regular web hosting from the repository yet.
I'm wondering a bit about the sphinx workflow. It seems like we should be able to autogenerate the docs from the sfepy source using sphinx. I was wondering if sphinx is already setup for sfepy, or should I work on that first? Once we get sphinx setup, can we just git pull sfepy, build the doc pages w/ sphinx, and the git push them to the documentation site? I'll try playing with the numpy source, so thanks for the
I have also some advice from Ondrej, I will post it here on Monday, as I that information is on my workplace computer only...
Ok, great!
Thanks! Logan
Hi Logan,
Logan Sorenson wrote:
I think we should setup also a page where users could post their examples/applications. Something like what we do at sfepy.kme.zcu.cz site, but open for everybody.
This is a really good idea. Since that page looks like it runs on moinmoin, do you think it's possible to simply copy it over to another host and then open it up for everyone? Does anyone know if github supports moinmoin?
Yes, the site runs on moinmoin. However I am not convinced that moinmoin is the way to go, maybe also those pages could be based on sphinx, what do you think? We could maintain them in a git repository easily, so that the examples could be downloaded and tried-out by anyone.
I would also like to set-up a sphinx-based documentation site for sfepy, like [2] or [3], probably using github. Any volunteers out there? I have made some attempts to learn how to do it, but have currently no time to go on. And yes, new functions added to sfepy are documented and use the sphinx-compatible format, following the numpy's standards.
If no one else wants to volunteer, I can look into this. It would be good to get someone with more experience with github/Sphinx to give some starting pointers. This is how numpy guys do it:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_BUILD_DOCS.txt
I looked a bit into github. I was able to setup a repository on github fairly easy, so hosting the docs is no problem on there. But I'm not sure how to do regular web hosting from the repository yet.
It is possible, see the notes below. I am open to alternatives, though - all I am persuaded is that we should use sphinx.
I'm wondering a bit about the sphinx workflow. It seems like we should be able to autogenerate the docs from the sfepy source using sphinx. I was wondering if sphinx is already setup for sfepy, or should I work on that first? Once we get sphinx setup, can we just git pull sfepy, build the doc pages w/ sphinx, and the git push them to the documentation site? I'll try playing with the numpy source, so thanks for the
Sphinx is not setup for sfepy yet, so this is the first step to undertake. It would be great if you could give it a shot!
The site [2] says how to have both the source code and the documentation in the same directory, but without unwanted interference, see the 'Project Pages' section.
I have also some advice from Ondrej, I will post it here on Monday, as I that information is on my workplace computer only...
Ok, great!
So I have founded the information - a success story [1] :), and how to setup github pages [2].
[1] http://lists.xiph.org/pipermail/theora/2009-June/002328.html [2] http://pages.github.com/
best, r.
Hi Robert,
On Mon, Oct 12, 2009 at 4:21 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
Hi Logan,
I think we should setup also a page where users could post their examples/applications. Something like what we do at sfepy.kme.zcu.cz site, but open for everybody.
This is a really good idea. Since that page looks like it runs on moinmoin, do you think it's possible to simply copy it over to another host and
Logan Sorenson wrote: then
open it up for everyone? Does anyone know if github supports moinmoin?
Yes, the site runs on moinmoin. However I am not convinced that moinmoin is the way to go, maybe also those pages could be based on sphinx, what do you think? We could maintain them in a git repository easily, so that the examples could be downloaded and tried-out by anyone.
That's true, after reading about the github pages I think moinmoin is just too much complexity. It's probably better just to keep them in the git repository.
I would also like to set-up a sphinx-based documentation site for sfepy, like [2] or [3], probably using github. Any volunteers out there? I have made some attempts to learn how to do it, but have currently no time to go on. And yes, new functions added to sfepy are documented and use the sphinx-compatible format, following the numpy's standards.
If no one else wants to volunteer, I can look into this. It would be good to get someone with more experience with github/Sphinx to give some starting pointers. This is how numpy guys do it:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_BUILD_DOCS.txt
I looked a bit into github. I was able to setup a repository on github fairly easy, so hosting the docs is no problem on there. But I'm not sure how to do regular web hosting from the repository yet.
It is possible, see the notes below. I am open to alternatives, though - all I am persuaded is that we should use sphinx.
Ok, I'm in agreement. :) Github pages seem very cool.
I'm wondering a bit about the sphinx workflow. It seems like we should be able to autogenerate the docs from the sfepy source using sphinx. I was wondering if sphinx is already setup for sfepy, or should I work on that first? Once we get sphinx setup, can we just git pull sfepy, build the doc pages w/ sphinx, and the git push them to the documentation site? I'll try playing with the numpy source, so thanks for the
Sphinx is not setup for sfepy yet, so this is the first step to undertake. It would be great if you could give it a shot!
The site [2] says how to have both the source code and the documentation in the same directory, but without unwanted interference, see the 'Project Pages' section.
I have also some advice from Ondrej, I will post it here on Monday, as I that information is on my workplace computer only...
Ok, great!
So I have founded the information - a success story [1] :), and how to setup github pages [2].
[1] http://lists.xiph.org/pipermail/theora/2009-June/002328.html [2] http://pages.github.com/
best, r.
Ok, I think I'll try to follow Ondrej's example for python-theora to setup the Sphinx doc. Hopefully all goes smoothly!
Best, Logan
Hi Logan,
Logan Sorenson wrote:
On Mon, Oct 12, 2009 at 4:21 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
Yes, the site runs on moinmoin. However I am not convinced that moinmoin is the way to go, maybe also those pages could be based on sphinx, what do you think? We could maintain them in a git repository easily, so that the examples could be downloaded and tried-out by anyone.
That's true, after reading about the github pages I think moinmoin is just too much complexity. It's probably better just to keep them in the git repository.
ok. let's try this then.
I would also like to set-up a sphinx-based documentation site for sfepy, like [2] or [3], probably using github. Any volunteers out there? I have made some attempts to learn how to do it, but have currently no time to go on. And yes, new functions added to sfepy are documented and use the sphinx-compatible format, following the numpy's standards.
If no one else wants to volunteer, I can look into this. It would be good to get someone with more experience with github/Sphinx to give some starting pointers. This is how numpy guys do it:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_BUILD_DOCS.txt
I looked a bit into github. I was able to setup a repository on github fairly easy, so hosting the docs is no problem on there. But I'm not sure how to do regular web hosting from the repository yet. It is possible, see the notes below. I am open to alternatives, though - all I am persuaded is that we should use sphinx.
Ok, I'm in agreement. :) Github pages seem very cool.
Yes, they have a well-thought design.
I'm wondering a bit about the sphinx workflow. It seems like we should be able to autogenerate the docs from the sfepy source using sphinx. I was wondering if sphinx is already setup for sfepy, or should I work on that first? Once we get sphinx setup, can we just git pull sfepy, build the doc pages w/ sphinx, and the git push them to the documentation site? I'll try playing with the numpy source, so thanks for the Sphinx is not setup for sfepy yet, so this is the first step to undertake. It would be great if you could give it a shot!
The site [2] says how to have both the source code and the documentation in the same directory, but without unwanted interference, see the 'Project Pages' section.
I have also some advice from Ondrej, I will post it here on Monday, as I that information is on my workplace computer only...
Ok, great! So I have founded the information - a success story [1] :), and how to setup github pages [2].
[1] http://lists.xiph.org/pipermail/theora/2009-June/002328.html [2] http://pages.github.com/
Ok, I think I'll try to follow Ondrej's example for python-theora to setup the Sphinx doc. Hopefully all goes smoothly!
Great! This would really help a lot, thank you.
cheers, r.
PS: This time-lagged discussion is rather slow, I have to get up early one day, or stay till night at work :)
Hi Robert,
There is an initial sphinx-based documentation at [1]. It seems like the html pages are being served, but the js/css is not working? Do you see that as well? It's strange because it works locally on my machine. So I need to figure out what's going on there. Does anyone know what the problem could be?
Also, you can pull the source from my github repository at [2]. Basically, I just added a few files in the doc directory using "sphinx-quickstart" and then hand-edited them as needed. Then, with sphinx installed, I can just run "make html" in the doc directory to build the documentation in doc/_build/html, which I copied into the gh-pages branch of the repository (following the instructions on github). So that part is quite simple. :)
So far, I've just added one class to the documentation as an example. The documentation process is (at least from what I read on the sphinx docs) semi-automatic in that the docstrings get pulled in after writing an rst file telling sphinx which docstrings to pulll. But I think that's better since it gives more control. I can try generating the documentation for the rest of the code as an exercise in familiarizing myself with the code base. But I have an exam on Thursday, so I probably can't get to it until after then. :)
On Tue, Oct 13, 2009 at 5:18 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
Great! This would really help a lot, thank you.
cheers, r.
PS: This time-lagged discussion is rather slow, I have to get up early one day, or stay till night at work :)
Glad to help out where I can! Hope to catch you online sometime, but don't adjust your schedule on my account :)
Best, Logan
[1] http://logansorenson.github.com/sfepy_doc2/ [2] git://github.com/logansorenson/sfepy_doc2.git
Hi Logan,
Logan Sorenson wrote:
Hi Robert,
There is an initial sphinx-based documentation at [1]. It seems like the html pages are being served, but the js/css is not working? Do you see that as well? It's strange because it works locally on my machine. So I need to figure out what's going on there. Does anyone know what the problem could be?
Awesome! Thanks for starting that, a good documentation is essential for attracting potential users/contributors.
I see the plain html pages as well. I have cloned [2], then tunning "make html" works perfectly, and the local pages do use the correct style-sheets.
I have tried to push to github some pages I had prepared a while ago for another project (http://rc.github.com/gensei/), and got the same problem - maybe it is related to the sphinx version (0.6.3)?
Also, you can pull the source from my github repository at [2]. Basically, I just added a few files in the doc directory using "sphinx-quickstart" and then hand-edited them as needed. Then, with sphinx installed, I can just run "make html" in the doc directory to build the documentation in doc/_build/html, which I copied into the gh-pages branch of the repository (following the instructions on github). So that part is quite simple. :)
Sphinx is really nice, yes. :)
So far, I've just added one class to the documentation as an example. The documentation process is (at least from what I read on the sphinx docs) semi-automatic in that the docstrings get pulled in after writing an rst file telling sphinx which docstrings to pulll. But I think that's better since it gives more control. I can try generating the documentation for the rest of the code as an exercise in familiarizing myself with the code base. But I have an exam on Thursday, so I probably can't get to it until after then. :)
Exactly. The rst files have to be written manually, but then the docstrings can be included automatically from the sources. It would be great if you try the exercise of generating the docs, thanks! But beware of skeletons in the cupboard!
Just in case you feel like contributing a docstring: note, that I am now redesigning sfepy.fem, so it's no point in writing docstrings there at this point - the code gets changed pretty fast. Also the classes in sfepy.terms use a custom docstring syntax designed for the 'gen' script that generates the sfepy_manual.pdf file. I guess it can be fixed to work with "sphinxified" docstrings, but IMHO once we get the sphinx docs in shape, it can be removed - I have just tried "make latex" (*) and it works perfectly.
Good luck with your exam, fingers crossed! :)
On Tue, Oct 13, 2009 at 5:18 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
PS: This time-lagged discussion is rather slow, I have to get up early one day, or stay till night at work :)
Glad to help out where I can! Hope to catch you online sometime, but don't adjust your schedule on my account :)
I am lurking at #sfepy IRC channel at freenode, when online... People can use that to spy on me whether I work or not ;)
Best, Logan
[1] http://logansorenson.github.com/sfepy_doc2/ [2] git://github.com/logansorenson/sfepy_doc2.git
cheers, r.
(*) $ make latex $ cd _build/latex $ make all-pdf
Hi Robert,
On Wed, Oct 14, 2009 at 4:58 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
Hi Logan,
Logan Sorenson wrote:
Hi Robert,
There is an initial sphinx-based documentation at [1]. It seems like the html pages are being served, but the js/css is not working? Do you see that as well? It's strange because it works locally on my machine. So I need to figure out what's going on there. Does anyone know what the problem could be?
Awesome! Thanks for starting that, a good documentation is essential for attracting potential users/contributors.
Yes, definitely good documentation is very helpful. Actually, one of the main reasons I like SfePy is the clear instructions and examples on the google page. :) I hope I can eventually contribute some tutorials/examples. By the way, what do you use to generate your meshes? I've been using gmsh which seems pretty good, but I was wondering if it's possible to define groups and regions in there for export to Sfepy.
I see the plain html pages as well. I have cloned [2], then tunning "make html" works perfectly, and the local pages do use the correct style-sheets.
I have tried to push to github some pages I had prepared a while ago for another project (http://rc.github.com/gensei/), and got the same problem - maybe it is related to the sphinx version (0.6.3)?
Ok, I found the problem. According to [3], the issue is the leading underscore, which has special meaning on github, in the _static and _sources directory names. After checking Ondrej's examples, I found the sphinx-to-github script, which you can get from [4]. The script just strips the underscore from these directories and any references. So you can check the site at [1] and it should be working now. :)
So far, I've just added one class to the documentation as an example. The documentation process is (at least from what I read on the sphinx docs) semi-automatic in that the docstrings get pulled in after writing an rst file telling sphinx which docstrings to pulll. But I think that's better since it gives more control. I can try generating the documentation for the rest of the code as an exercise in familiarizing myself with the code base. But I have an exam on Thursday, so I probably can't get to it until after then. :)
Exactly. The rst files have to be written manually, but then the docstrings can be included automatically from the sources. It would be great if you try the exercise of generating the docs, thanks! But beware of skeletons in the cupboard!
Hahaha, I'll be careful! :D
Just in case you feel like contributing a docstring: note, that I am now redesigning sfepy.fem, so it's no point in writing docstrings there at this point - the code gets changed pretty fast. Also the classes in sfepy.terms use a custom docstring syntax designed for the 'gen' script that generates the sfepy_manual.pdf file. I guess it can be fixed to work with "sphinxified" docstrings, but IMHO once we get the sphinx docs in shape, it can be removed - I have just tried "make latex" (*) and it works perfectly.
Ok, thanks for the warning, I'll leave sfepy.fem alone for now. I think once the code structure stabilizes, it should be quite easy to write the docs, since they will follow the same structure. I can make some placeholders with warnings in the areas that the code is rapidly changing. By the way, "make latex" is working here too. So I think eventually we can merge in your work on the generation of terms, but I guess we can take it as it comes.
Good luck with your exam, fingers crossed! :)
Thanks! Logan
[1] http://logansorenson.github.com/sfepy_doc2/ [2] git://github.com/logansorenson/sfepy_doc2.git [3] http://support.github.com/discussions/site/268-gh-pages-has-sub-dirs-but-the... [4] http://github.com/michaeljones/sphinx-to-github
Hi Logan,
Logan Sorenson wrote:
Hi Robert,
On Wed, Oct 14, 2009 at 4:58 AM, Robert Cimrman cimr...@ntc.zcu.cz
Awesome! Thanks for starting that, a good documentation is essential for attracting potential users/contributors.
Yes, definitely good documentation is very helpful. Actually, one of the main reasons I like SfePy is the clear instructions and examples on the google page. :) I hope I can eventually contribute some tutorials/examples. By the way, what do you use to generate your meshes? I've been using gmsh which seems pretty good, but I was wondering if it's possible to define groups and regions in there for export to Sfepy.
Thanks, you are too kind here, the google page lags behind the code in some areas. But it gives the idea, I hope.
For simple meshes (block, tube) I use the blockgen.py and cylindergen.py in 'scripts/'. For complex meshes I usually bugger people around my department who use commercial programs. So I do not know gmsh much. But I made a gmsh script that defined element groups, see the attachment. Use something like:
os.system("gmsh -2 %s -format mesh" % 'mesh.geo') os.system("script/mesh_to_vtk.py %s %s" % ('mesh.mesh', 'mesh.vtk'))
It seems that each Plane Surface in mesh.geo gets a different group id.
Ok, I found the problem. According to [3], the issue is the leading underscore, which has special meaning on github, in the _static and _sources directory names. After checking Ondrej's examples, I found the sphinx-to-github script, which you can get from [4]. The script just strips the underscore from these directories and any references. So you can check the site at [1] and it should be working now. :)
Now that clearly shows how my memory is bad - I recall knowing about this issue :] Thanks for finding it out!
Ok, thanks for the warning, I'll leave sfepy.fem alone for now. I think once the code structure stabilizes, it should be quite easy to write the docs, since they will follow the same structure. I can make some placeholders with warnings in the areas that the code is rapidly changing. By the way, "make latex" is working here too. So I think eventually we can merge in your work on the generation of terms, but I guess we can take it as it comes.
Yes, a placeholder would do for the moment. I will transform the latex sources of sfepy manual to rst as soon as I have a spare moment.
[1] http://logansorenson.github.com/sfepy_doc2/ [2] git://github.com/logansorenson/sfepy_doc2.git [3] http://support.github.com/discussions/site/268-gh-pages-has-sub-dirs-but-the... [4] http://github.com/michaeljones/sphinx-to-github
cheers, r.
a = 1.000000; out = 0.200000; in = 0.050000; Point(1) = {-a,-a,0, out}; Point(2) = {-a,a,0, out}; Point(3) = {a, a,0, out}; Point(4) = {a,-a,0, out}; Point(5) = {0,0,0, in}; Line(1) = {1,4}; Line(2) = {4,3}; Line(3) = {3,2}; Line(4) = {2,1}; Line Loop(1) = {2,3,4,1}; r = 0.100000; Point(6) = {r,0,0, in}; Point(7) = {0,r,0, in}; Point(8) = {-r, 0,0, in}; Point(9) = {0,-r,0, in}; Circle(6) = {6,5,7}; Circle(7) = {7,5,8}; Circle(8) = {8,5,9}; Circle(9) = {9,5,6}; Line Loop(2) = {6,7,8,9}; r = 0.187500; Point(10) = {r,0,0, in}; Point(11) = {0,r,0, in}; Point(12) = {-r, 0,0, in}; Point(13) = {0,-r,0, in}; Circle(10) = {10,5,11}; Circle(11) = {11,5,12}; Circle(12) = {12,5,13}; Circle(13) = {13,5,10}; Line Loop(3) = {10,11,12,13}; r = 0.275000; Point(14) = {r,0,0, in}; Point(15) = {0,r,0, in}; Point(16) = {-r, 0,0, in}; Point(17) = {0,-r,0, in}; Circle(14) = {14,5,15}; Circle(15) = {15,5,16}; Circle(16) = {16,5,17}; Circle(17) = {17,5,14}; Line Loop(4) = {14,15,16,17}; r = 0.362500; Point(18) = {r,0,0, in}; Point(19) = {0,r,0, in}; Point(20) = {-r, 0,0, in}; Point(21) = {0,-r,0, in}; Circle(18) = {18,5,19}; Circle(19) = {19,5,20}; Circle(20) = {20,5,21}; Circle(21) = {21,5,18}; Line Loop(5) = {18,19,20,21}; r = 0.450000; Point(22) = {r,0,0, in}; Point(23) = {0,r,0, in}; Point(24) = {-r, 0,0, in}; Point(25) = {0,-r,0, in}; Circle(22) = {22,5,23}; Circle(23) = {23,5,24}; Circle(24) = {24,5,25}; Circle(25) = {25,5,22}; Line Loop(6) = {22,23,24,25}; r = 0.537500; Point(26) = {r,0,0, in}; Point(27) = {0,r,0, in}; Point(28) = {-r, 0,0, in}; Point(29) = {0,-r,0, in}; Circle(26) = {26,5,27}; Circle(27) = {27,5,28}; Circle(28) = {28,5,29}; Circle(29) = {29,5,26}; Line Loop(7) = {26,27,28,29}; r = 0.625000; Point(30) = {r,0,0, in}; Point(31) = {0,r,0, in}; Point(32) = {-r, 0,0, in}; Point(33) = {0,-r,0, in}; Circle(30) = {30,5,31}; Circle(31) = {31,5,32}; Circle(32) = {32,5,33}; Circle(33) = {33,5,30}; Line Loop(8) = {30,31,32,33}; r = 0.712500; Point(34) = {r,0,0, in}; Point(35) = {0,r,0, in}; Point(36) = {-r, 0,0, in}; Point(37) = {0,-r,0, in}; Circle(34) = {34,5,35}; Circle(35) = {35,5,36}; Circle(36) = {36,5,37}; Circle(37) = {37,5,34}; Line Loop(9) = {34,35,36,37}; r = 0.800000; Point(38) = {r,0,0, in}; Point(39) = {0,r,0, in}; Point(40) = {-r, 0,0, in}; Point(41) = {0,-r,0, in}; Circle(38) = {38,5,39}; Circle(39) = {39,5,40}; Circle(40) = {40,5,41}; Circle(41) = {41,5,38}; Line Loop(10) = {38,39,40,41}; Plane Surface(1) = {1,10}; Plane Surface(2) = {2}; Plane Surface(3) = {3,2}; Plane Surface(4) = {4,3}; Plane Surface(5) = {5,4}; Plane Surface(6) = {6,5}; Plane Surface(7) = {7,6}; Plane Surface(8) = {8,7}; Plane Surface(9) = {9,8}; Plane Surface(10) = {10,9}; Physical Surface(1) = {1}; Physical Surface(2) = {2,3,4,5,6,7,8,9,10};
Hi Robert,
I finally got some time to update the documentation. The results are at [1] and you can pull the github repo at [2]. I finished most of the sfepy directory, except for fem and terms. Using the sphinx automodule directive with the members and undoc-members sped things up considerably. Let me know if you like the resulting style, or if it should be changed.
Currently, there's an rst file for each module in the sfepy hierarchy. I'm wondering if I should roll it all into one big file, or do you think it's fine the way it is?
Also, I encountered some issues with the formatting of the docstring. Most were warnings (probably due to the docstrings not yet being in sphinx compatible format), but I got several of the following types of errors:
logan@quantumdot:~/projects/sfepy/doc$ make html PYTHONPATH=.. sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v0.6.3 loading pickled environment... done building [html]: targets for 1 source files that are out of date updating environment: 15 added, 1 changed, 0 removed reading sources... [ 18%] module_sfepy_geom_geometry reST markup error: /home/logan/projects/sfepy/sfepy/geom/geometry.py:docstring of sfepy.geom.geometry.geometry:13: (SEVERE/4) Unexpected section title.
Example:
make: *** [html] Error 1
It looks like we aren't allowed to have sections in the docstrings for the sphinx autodoc. So I removed the underscore line and appended a colon in the source code when I encountered these problems. Do you think this is good, or should I look for a better solution?
Finally, I put some placeholders in for the other manuals in the documentation. I'm thinking something like the following:
introduction tutorial users_guide examples developer_guide <--- currently has sfepy module documentation documentation_guide
Any suggestions/thoughts here?
Thanks! Logan
[1] http://logansorenson.github.com/sfepy_doc2/ [2] git://github.com/logansorenson/sfepy_doc2.git
Hi Logan,
Logan Sorenson wrote:
Hi Robert,
I finally got some time to update the documentation. The results are at [1] and you can pull the github repo at [2]. I finished most of the sfepy directory, except for fem and terms. Using the sphinx automodule directive with the members and undoc-members sped things up considerably. Let me know if you like the resulting style, or if it should be changed.
Fantastic! I was not aware of undoc-members - now I can learn sphinx by example which is the best way.
Currently, there's an rst file for each module in the sfepy hierarchy. I'm wondering if I should roll it all into one big file, or do you think it's fine the way it is?
I also prefer having more smaller files than one big, let's keep it that way. It makes the git commits more readable, too - one can see immediately what parts of the docs were updated etc.
Also, I encountered some issues with the formatting of the docstring. Most were warnings (probably due to the docstrings not yet being in sphinx compatible format), but I got several of the following types of errors:
logan@quantumdot:~/projects/sfepy/doc$ make html PYTHONPATH=.. sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v0.6.3 loading pickled environment... done building [html]: targets for 1 source files that are out of date updating environment: 15 added, 1 changed, 0 removed reading sources... [ 18%] module_sfepy_geom_geometry reST markup error: /home/logan/projects/sfepy/sfepy/geom/geometry.py:docstring of sfepy.geom.geometry.geometry:13: (SEVERE/4) Unexpected section title.
Example:
make: *** [html] Error 1
It looks like we aren't allowed to have sections in the docstrings for the sphinx autodoc. So I removed the underscore line and appended a colon in the source code when I encountered these problems. Do you think this is good, or should I look for a better solution?
Let's have a look how numpy does this. For example the docstring of the sine function is:
sin(x[, out])
Trigonometric sine, element-wise.
Parameters
x : array_like
Angle, in radians (:math:2 \pi rad equals 360 degrees).
Returns
y : array_like The sine of each element of x.
This is what I have tried to mimic, as I like the look of the textual form. The underlines make it pretty readable IMHO. But, as you noticed, sphinx chokes at that - that's because numpy uses some sphinx extensions as described in [3].
So we have basically two options: (1) stick with the plain sphinx format, or (2) use the numpy extensions.
I am in favor of (2), but you are the one who actually makes the docs, so what do you think?
Finally, I put some placeholders in for the other manuals in the documentation. I'm thinking something like the following:
introduction tutorial users_guide examples developer_guide <--- currently has sfepy module documentation documentation_guide
Any suggestions/thoughts here?
This is good. Maybe the introduction can be directly in the index.rst so that it is the first thing a visitor sees? Is 'installation' going into the tutorial? Maybe a section just after the introduction would be better.
I have added a very basic introduction and a stub of a tutorial to [4]. Feel free to edit it and correct my lame English.
BTW. after I have cloned the new version, I have a problem building the html docs:
$ make html PYTHONPATH=.. sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v0.6.3 loading pickled environment... not found building [html]: targets for 46 source files that are out of date updating environment: 46 added, 0 changed, 0 removed make: *** [html] Segmentation fault
This happens when the sfepy extension modules are compiled. If they are not compiled, 'make html' works apart from printing lots of warnings that the modules are not compiled (what a sentence! :)).
Have you encountered this?
Thanks! Logan
[1] http://logansorenson.github.com/sfepy_doc2/ [2] git://github.com/logansorenson/sfepy_doc2.git
[3] http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_BUILD_DOCS.txt [4] git://github.com/rc/sfepy.git (branch 'doc', http://github.com/rc/sfepy)
cheers and thanks! r.
PS: the exam passed well, right?
Hi Robert,
On Tue, Oct 20, 2009 at 7:10 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
Hi Logan,
Logan Sorenson wrote:
Hi Robert,
I finally got some time to update the documentation. The results are at [1] and you can pull the github repo at [2]. I finished most of the sfepy directory, except for fem and terms. Using the sphinx automodule directive with the members and undoc-members sped things up considerably. Let me know if you like the resulting style, or if it should be changed.
Fantastic! I was not aware of undoc-members - now I can learn sphinx by example which is the best way.
Currently, there's an rst file for each module in the sfepy hierarchy. I'm wondering if I should roll it all into one big file, or do you think it's fine the way it is?
I also prefer having more smaller files than one big, let's keep it that way. It makes the git commits more readable, too - one can see immediately what parts of the docs were updated etc.
Ok, I'll keep them as separate files. I just wasn't sure if it was making the doc directory too cluttered. :)
Also, I encountered some issues with the formatting of the docstring. Most were warnings (probably due to the docstrings not yet being in sphinx compatible format), but I got several of the following types of errors:
logan@quantumdot:~/projects/sfepy/doc$ make html PYTHONPATH=.. sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v0.6.3 loading pickled environment... done building [html]: targets for 1 source files that are out of date updating environment: 15 added, 1 changed, 0 removed reading sources... [ 18%] module_sfepy_geom_geometry reST markup error: /home/logan/projects/sfepy/sfepy/geom/geometry.py:docstring of sfepy.geom.geometry.geometry:13: (SEVERE/4) Unexpected section title.
Example:
make: *** [html] Error 1
It looks like we aren't allowed to have sections in the docstrings for the sphinx autodoc. So I removed the underscore line and appended a colon in the source code when I encountered these problems. Do you think this is good, or should I look for a better solution?
Let's have a look how numpy does this. For example the docstring of the sine function is:
sin(x[, out])
Trigonometric sine, element-wise.
Parameters
x : array_like Angle, in radians (:math:
2 \pirad equals 360 degrees).Returns
y : array_like The sine of each element of x.
This is what I have tried to mimic, as I like the look of the textual form. The underlines make it pretty readable IMHO. But, as you noticed, sphinx chokes at that - that's because numpy uses some sphinx extensions as described in [3].
So we have basically two options: (1) stick with the plain sphinx format, or (2) use the numpy extensions.
I am in favor of (2), but you are the one who actually makes the docs, so what do you think?
Ok, actually I think (2) is better too. I forgot about the numpy extensions, so I'll have another look through that to see if I can set it up.
Finally, I put some placeholders in for the other manuals in the documentation. I'm thinking something like the following:
introduction tutorial users_guide examples developer_guide <--- currently has sfepy module documentation documentation_guide
Any suggestions/thoughts here?
This is good. Maybe the introduction can be directly in the index.rst so that it is the first thing a visitor sees? Is 'installation' going into the tutorial? Maybe a section just after the introduction would be better.
This makes very good sense.
I have added a very basic introduction and a stub of a tutorial to [4]. Feel free to edit it and correct my lame English.
Ok, great! I will merge this in!
BTW. after I have cloned the new version, I have a problem building the html docs:
$ make html PYTHONPATH=.. sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v0.6.3 loading pickled environment... not found building [html]: targets for 46 source files that are out of date updating environment: 46 added, 0 changed, 0 removed make: *** [html] Segmentation fault
This happens when the sfepy extension modules are compiled. If they are not compiled, 'make html' works apart from printing lots of warnings that the modules are not compiled (what a sentence! :)).
Have you encountered this?
I haven't seen any segmentation faults. I'm using Sphinx version 0.6.3 from debian sid so I'm not doing any compiling here (as far as I know :) ). By extension modules, are you referring to the autodoc extension (which per my understanding is built into sphinx), or the numpy extensions? I'll let you know if I notice any unusual behavior once I've gotten a chance to look at the numpy stuff.
Thanks! Logan
[1] http://logansorenson.github.com/sfepy_doc2/ [2] git://github.com/logansorenson/sfepy_doc2.git
[3] http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_BUILD_DOCS.txt [4] git://github.com/rc/sfepy.git (branch 'doc', http://github.com/rc/sfepy)
cheers and thanks! r.
PS: the exam passed well, right?
I haven't gotten the results back yet...but I think I did fairly well. :) Thanks for asking!
Best regards, Logan
Hi Logan,
Logan Sorenson wrote:
Ok, I'll keep them as separate files. I just wasn't sure if it was making the doc directory too cluttered. :)
Well, if it is possible to have those files in directories following the sfepy source tree structure, it might be better, but it is ok as it is, too.
So we have basically two options: (1) stick with the plain sphinx format, or (2) use the numpy extensions.
I am in favor of (2), but you are the one who actually makes the docs, so what do you think?
Ok, actually I think (2) is better too. I forgot about the numpy extensions, so I'll have another look through that to see if I can set it up.
ok, so (2) is agreed upon.
BTW. after I have cloned the new version, I have a problem building the html docs:
$ make html PYTHONPATH=.. sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v0.6.3 loading pickled environment... not found building [html]: targets for 46 source files that are out of date updating environment: 46 added, 0 changed, 0 removed make: *** [html] Segmentation fault
This happens when the sfepy extension modules are compiled. If they are not compiled, 'make html' works apart from printing lots of warnings that the modules are not compiled (what a sentence! :)).
Have you encountered this?
I haven't seen any segmentation faults. I'm using Sphinx version 0.6.3 from debian sid so I'm not doing any compiling here (as far as I know :) ). By extension modules, are you referring to the autodoc extension (which per my understanding is built into sphinx), or the numpy extensions? I'll let you know if I notice any unusual behavior once I've gotten a chance to look at the numpy stuff.
By extension modules I mean the sfepy extension modules - the term assembling functions in sfepy/terms/extmods and the FE stuff in sfepy/fem/extmods. Something strange is happening here - I do not see why this should kill the sphinx.
PS: the exam passed well, right?
I haven't gotten the results back yet...but I think I did fairly well. :) Thanks for asking!
Glad to hear that :)
cheers, r.
Hi Robert,
On Wed, Oct 21, 2009 at 3:11 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
Hi Logan,
Logan Sorenson wrote:
Ok, I'll keep them as separate files. I just wasn't sure if it was making the doc directory too cluttered. :)
Well, if it is possible to have those files in directories following the sfepy source tree structure, it might be better, but it is ok as it is, too.
Good idea, done! :) (See [1] & [2]) I also merged in your intro, etc.
So we have basically two options: (1) stick with the plain sphinx format, or (2) use the numpy extensions.
I am in favor of (2), but you are the one who actually makes the docs, so what do you think?
Ok, actually I think (2) is better too. I forgot about the numpy extensions, so I'll have another look through that to see if I can set it up.
ok, so (2) is agreed upon.
Ok, I installed numpydoc using easy_install per [3] and updated doc/conf.py to use numpydoc and reverted the source files. I also changed the docstring of the geometry class in sfepy/geom/geometry.py (since sphinx with numpydoc wasn't liking it) to:
Examples
Basically, we just have to try to match the numpy style as much as possible, e.g. [5].
One issue that I noticed is I have to use numpydoc.autosummary to get the module documentation to autogenerate. For some reason, using sphinx.ext.autosummary is not enough, even though numpydoc.autosummary is deprecated and suggested to be replaced with sphinx.ext.autosummary.
BTW. after I have cloned the new version, I have a problem building the html docs:
$ make html PYTHONPATH=.. sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v0.6.3 loading pickled environment... not found building [html]: targets for 46 source files that are out of date updating environment: 46 added, 0 changed, 0 removed make: *** [html] Segmentation fault
This happens when the sfepy extension modules are compiled. If they are not compiled, 'make html' works apart from printing lots of warnings that the modules are not compiled (what a sentence! :)).
Have you encountered this?
I haven't seen any segmentation faults. I'm using Sphinx version 0.6.3 from debian sid so I'm not doing any compiling here (as far as I know :) ). By extension modules, are you referring to the autodoc extension (which per my understanding is built into sphinx), or the numpy extensions? I'll let you know if I notice any unusual behavior once I've gotten a chance to look at the numpy stuff.
By extension modules I mean the sfepy extension modules - the term assembling functions in sfepy/terms/extmods and the FE stuff in sfepy/fem/extmods. Something strange is happening here - I do not see why this should kill the sphinx.
Hmm, yes, this is strange. I don't notice any strange behavior from sphinx and I'm compiling the sfepy extension modules (sorry for the confusion there, I was kind of tired when I wrote the last mail :)) My only guess is that sphinx has to be able to import the module in order to autogenerate the documentation from the doc strings. Does python segfault when you load the extension modules? Everything seems ok here...
cheers, r.
Thanks again, as always :)
Logan
[1] http://logansorenson.github.com/sfepy_doc2/ [2] git://github.com/logansorenson/sfepy_doc2.git [3] http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_BUILD_DOCS.txt [4] git://github.com/rc/sfepy.git (branch 'doc', http://github.com/rc/sfepy)
Oops, here's [5]: http://svn.scipy.org/svn/numpy/trunk/doc/EXAMPLE_DOCSTRING.txt
Hi Logan,
Logan Sorenson wrote:
On Wed, Oct 21, 2009 at 3:11 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
Ok, I'll keep them as separate files. I just wasn't sure if it was making the doc directory too cluttered. :) Well, if it is possible to have those files in directories following the sfepy
Logan Sorenson wrote: source tree structure, it might be better, but it is ok as it is, too.
Good idea, done! :) (See [1] & [2]) I also merged in your intro, etc.
Thank you! The welcome page starts to look like the documentation is really there :) Now we should fill in the tutorial, and merge in the sfepy_manual.pdf stuff. I won't be probably able to do in in next two weeks (but miracles sometimes happen), though, so feel free to play with it, if you are luckier than me in terms of spare time.
Ok, I installed numpydoc using easy_install per [3] and updated doc/conf.py to use numpydoc and reverted the source files. I also changed the docstring of the geometry class in sfepy/geom/geometry.py (since sphinx with numpydoc wasn't liking it) to:
Examples
Fine, thanks! The docstrings of terms all use the custom syntax the 'genDocs.py' script needs, sphinx is not going to like that, too. There are tons of them, so maybe the 'genDocs.py' could be tweaked to hammer the docstring into the right shape, as it scans and parses them anyway.
Basically, we just have to try to match the numpy style as much as possible, e.g. [5].
Now that's a literate programming! :)
One issue that I noticed is I have to use numpydoc.autosummary to get the module documentation to autogenerate. For some reason, using sphinx.ext.autosummary is not enough, even though numpydoc.autosummary is deprecated and suggested to be replaced with sphinx.ext.autosummary.
You can try asking the numpy crowd (numpy-di...@scipy.org), but I guess it's ok as long as it works ;)
BTW. after I have cloned the new version, I have a problem building the html docs:
$ make html PYTHONPATH=.. sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v0.6.3 loading pickled environment... not found building [html]: targets for 46 source files that are out of date updating environment: 46 added, 0 changed, 0 removed make: *** [html] Segmentation fault
This happens when the sfepy extension modules are compiled. If they are not compiled, 'make html' works apart from printing lots of warnings that the modules are not compiled (what a sentence! :)).
Have you encountered this?
I haven't seen any segmentation faults. I'm using Sphinx version 0.6.3 from debian sid so I'm not doing any compiling here (as far as I know :) ). By extension modules, are you referring to the autodoc extension (which per my understanding is built into sphinx), or the numpy extensions? I'll let you know if I notice any unusual behavior once I've gotten a chance to look at the numpy stuff. By extension modules I mean the sfepy extension modules - the term assembling functions in sfepy/terms/extmods and the FE stuff in sfepy/fem/extmods. Something strange is happening here - I do not see why this should kill the sphinx.
Hmm, yes, this is strange. I don't notice any strange behavior from sphinx and I'm compiling the sfepy extension modules (sorry for the confusion there, I was kind of tired when I wrote the last mail :)) My only guess is that sphinx has to be able to import the module in order to autogenerate the documentation from the doc strings. Does python segfault when you load the extension modules? Everything seems ok here...
Python is ok - the modules are loaded e.g. by running the tests, and all tests pass.
I get
Core was generated by `/usr/bin/python2.5 /usr/bin/sphinx-build -b html -d _build/doctrees . _build/ht'.
As you may notice, I still use python 2.5 - do you use 2.6?
thanks for your help! r.
Hi Robert,
On Thu, Oct 22, 2009 at 4:47 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
Hi Logan,
Logan Sorenson wrote:
On Wed, Oct 21, 2009 at 3:11 AM, Robert Cimrman cimr...@ntc.zcu.cz wrote:
Ok, I'll keep them as separate files. I just wasn't sure if it was making the doc directory too cluttered. :) Well, if it is possible to have those files in directories following the sfepy
Logan Sorenson wrote: source tree structure, it might be better, but it is ok as it is, too.
Good idea, done! :) (See [1] & [2]) I also merged in your intro, etc.
Thank you! The welcome page starts to look like the documentation is really there :) Now we should fill in the tutorial, and merge in the sfepy_manual.pdf stuff. I won't be probably able to do in in next two weeks (but miracles sometimes happen), though, so feel free to play with it, if you are luckier than me in terms of spare time.
You're welcome! I'll try to fill in as much as I can over the next few weeks (hopefully this weekend). I'll start with the existing web-pages and then try augmenting where I can.
Ok, I installed numpydoc using easy_install per [3] and updated doc/conf.py to use numpydoc and reverted the source files. I also changed the docstring of the geometry class in sfepy/geom/geometry.py (since sphinx with numpydoc wasn't liking it) to:
Examples
Fine, thanks! The docstrings of terms all use the custom syntax the 'genDocs.py' script needs, sphinx is not going to like that, too. There are tons of them, so maybe the 'genDocs.py' could be tweaked to hammer the docstring into the right shape, as it scans and parses them anyway.
Ok, I'll have a look into genDocs.py.
Basically, we just have to try to match the numpy style as much as possible, e.g. [5].
Now that's a literate programming! :)
Perhaps that particular example is overkill. :) I'm trying to document as much as possible on the mailing list what I did so others can recreate it if necessary. Sorry if I'm repeating stuff you already know. :)
One issue that I noticed is I have to use numpydoc.autosummary to get the module documentation to autogenerate. For some reason, using sphinx.ext.autosummary is not enough, even though numpydoc.autosummary is deprecated and suggested to be replaced with sphinx.ext.autosummary.
You can try asking the numpy crowd (numpy-di...@scipy.org), but I guess it's ok as long as it works ;)
I think it's ok for now, but I'll look around some more over on the numpy side to see where numpydoc is headed in the future. I don't want to get into maintaining a fork of numpydoc in sfepy's code base. :)
BTW. after I have cloned the new version, I have a problem building the html docs:
$ make html PYTHONPATH=.. sphinx-build -b html -d _build/doctrees . _build/html Running Sphinx v0.6.3 loading pickled environment... not found building [html]: targets for 46 source files that are out of date updating environment: 46 added, 0 changed, 0 removed make: *** [html] Segmentation fault
This happens when the sfepy extension modules are compiled. If they are not compiled, 'make html' works apart from printing lots of warnings that the modules are not compiled (what a sentence! :)).
Have you encountered this?
I haven't seen any segmentation faults. I'm using Sphinx version 0.6.3 from debian sid so I'm not doing any compiling here (as far as I know :) ). By extension modules, are you referring to the autodoc extension (which per my understanding is built into sphinx), or the numpy extensions? I'll let you know if I notice any unusual behavior once I've gotten a chance to look at the numpy stuff. By extension modules I mean the sfepy extension modules - the term assembling functions in sfepy/terms/extmods and the FE stuff in sfepy/fem/extmods. Something strange is happening here - I do not see why this should kill the sphinx.
Hmm, yes, this is strange. I don't notice any strange behavior from sphinx and I'm compiling the sfepy extension modules (sorry for the confusion there, I was kind of tired when I wrote the last mail :)) My only guess is that sphinx has to be able to import the module in order to autogenerate the documentation from the doc strings. Does python segfault when you load the extension modules? Everything seems ok here...
Python is ok - the modules are loaded e.g. by running the tests, and all tests pass.
I get
Core was generated by `/usr/bin/python2.5 /usr/bin/sphinx-build -b html -d _build/doctrees . _build/ht'.
As you may notice, I still use python 2.5 - do you use 2.6?
I'm using 2.5.4 over here...basically, I just run "python setup.py build_ext --inplace" in the sfepy root and then cd into the doc directory and run "make html". I attached the output of these two commands in case it helps. Do you do something different to compile the extension modules?
thanks for your help! r.
You're welcome!
Thanks, Logan
Logan Sorenson wrote:
You're welcome! I'll try to fill in as much as I can over the next few weeks (hopefully this weekend). I'll start with the existing web-pages and then try augmenting where I can.
That would be really great, thanks!
Fine, thanks! The docstrings of terms all use the custom syntax the 'genDocs.py' script needs, sphinx is not going to like that, too. There are tons of them, so maybe the 'genDocs.py' could be tweaked to hammer the docstring into the right shape, as it scans and parses them anyway.
Ok, I'll have a look into genDocs.py.
Skeleton alert on red level, beware :)
Basically, we just have to try to match the numpy style as much as possible, e.g. [5]. Now that's a literate programming! :)
Perhaps that particular example is overkill. :) I'm trying to document as much as possible on the mailing list what I did so others can recreate it if necessary. Sorry if I'm repeating stuff you already know. :)
Go on please, it's very good to have all the information together. :) The example [5] demonstrates all the possibilities, you are right that we need not them all. A more reasonable aim is to have some docstring in every function or method - still long way to go.
One issue that I noticed is I have to use numpydoc.autosummary to get the module documentation to autogenerate. For some reason, using sphinx.ext.autosummary is not enough, even though numpydoc.autosummary is deprecated and suggested to be replaced with sphinx.ext.autosummary. You can try asking the numpy crowd (numpy-di...@scipy.org), but I guess it's ok as long as it works ;)
I think it's ok for now, but I'll look around some more over on the numpy side to see where numpydoc is headed in the future. I don't want to get into maintaining a fork of numpydoc in sfepy's code base. :)
Sure, that is not an option, we have to use the standard tools, so that other kind people maintain them for us :)
Hmm, yes, this is strange. I don't notice any strange behavior from sphinx and I'm compiling the sfepy extension modules (sorry for the confusion there, I was kind of tired when I wrote the last mail :)) My only guess is that sphinx has to be able to import the module in order to autogenerate the documentation from the doc strings. Does python segfault when you load the extension modules? Everything seems ok here... Python is ok - the modules are loaded e.g. by running the tests, and all tests pass.
I get
Core was generated by `/usr/bin/python2.5 /usr/bin/sphinx-build -b html -d _build/doctrees . _build/ht'.
As you may notice, I still use python 2.5 - do you use 2.6?
I'm using 2.5.4 over here...basically, I just run "python setup.py build_ext --inplace" in the sfepy root and then cd into the doc directory and run "make html". I attached the output of these two commands in case it helps. Do you do something different to compile the extension modules?
I usually build simply by running "make". But anyway, I get the same segfault after "python setup.py build_ext --inplace". Have to check sanity of my installation some time. Thanks for the log, will check it too.
cheers, r.
participants (2)
-
Logan Sorenson -
Robert Cimrman