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.
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)?
Also, you can pull the source from my github repository at [2]. Basically, I just added a few files in the doc directory using "sphinx-quickstart" and then hand-edited them as needed. Then, with sphinx installed, I can just run "make html" in the doc directory to build the documentation in doc/_build/html, which I copied into the gh-pages branch of the repository (following the instructions on github). So that part is quite simple. :)
Sphinx is really nice, yes. :)
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!
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.
Good luck with your exam, fingers crossed! :)
On Tue, Oct 13, 2009 at 5:18 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
PS: This time-lagged discussion is rather slow, I have to get up early one day, or stay till night at work :)
Glad to help out where I can! Hope to catch you online sometime, but don't adjust your schedule on my account :)
I am lurking at #sfepy IRC channel at freenode, when online... People can use that to spy on me whether I work or not ;)
Best, Logan
[1] http://logansorenson.github.com/sfepy_doc2/ [2] git://github.com/logansorenson/sfepy_doc2.git
cheers, r.
(*) $ make latex $ cd _build/latex $ make all-pdf