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 \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?
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