Hi Robert,
On Wed, Oct 14, 2009 at 4:58 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
Hi Logan,
Logan Sorenson wrote:
Hi Robert,
There is an initial sphinx-based documentation at [1]. It seems like the html pages are being served, but the js/css is not working? Do you see that as well? It's strange because it works locally on my machine. So I need to figure out what's going on there. Does anyone know what the problem could be?
Awesome! Thanks for starting that, a good documentation is essential for attracting potential users/contributors.
Yes, definitely good documentation is very helpful. Actually, one of the main reasons I like SfePy is the clear instructions and examples on the google page. :) I hope I can eventually contribute some tutorials/examples. By the way, what do you use to generate your meshes? I've been using gmsh which seems pretty good, but I was wondering if it's possible to define groups and regions in there for export to Sfepy.
I see the plain html pages as well. I have cloned [2], then tunning "make html" works perfectly, and the local pages do use the correct style-sheets.
I have tried to push to github some pages I had prepared a while ago for another project (http://rc.github.com/gensei/), and got the same problem - maybe it is related to the sphinx version (0.6.3)?
Ok, I found the problem. According to [3], the issue is the leading underscore, which has special meaning on github, in the _static and _sources directory names. After checking Ondrej's examples, I found the sphinx-to-github script, which you can get from [4]. The script just strips the underscore from these directories and any references. So you can check the site at [1] and it should be working now. :)
So far, I've just added one class to the documentation as an example. The documentation process is (at least from what I read on the sphinx docs) semi-automatic in that the docstrings get pulled in after writing an rst file telling sphinx which docstrings to pulll. But I think that's better since it gives more control. I can try generating the documentation for the rest of the code as an exercise in familiarizing myself with the code base. But I have an exam on Thursday, so I probably can't get to it until after then. :)
Exactly. The rst files have to be written manually, but then the docstrings can be included automatically from the sources. It would be great if you try the exercise of generating the docs, thanks! But beware of skeletons in the cupboard!
Hahaha, I'll be careful! :D
Just in case you feel like contributing a docstring: note, that I am now redesigning sfepy.fem, so it's no point in writing docstrings there at this point - the code gets changed pretty fast. Also the classes in sfepy.terms use a custom docstring syntax designed for the 'gen' script that generates the sfepy_manual.pdf file. I guess it can be fixed to work with "sphinxified" docstrings, but IMHO once we get the sphinx docs in shape, it can be removed - I have just tried "make latex" (*) and it works perfectly.
Ok, thanks for the warning, I'll leave sfepy.fem alone for now. I think once the code structure stabilizes, it should be quite easy to write the docs, since they will follow the same structure. I can make some placeholders with warnings in the areas that the code is rapidly changing. By the way, "make latex" is working here too. So I think eventually we can merge in your work on the generation of terms, but I guess we can take it as it comes.
Good luck with your exam, fingers crossed! :)
Thanks! Logan
[1] http://logansorenson.github.com/sfepy_doc2/ [2] git://github.com/logansorenson/sfepy_doc2.git [3] http://support.github.com/discussions/site/268-gh-pages-has-sub-dirs-but-the... [4] http://github.com/michaeljones/sphinx-to-github