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.