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)