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?