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