Hi Logan,
Logan Sorenson wrote:
On Mon, Oct 12, 2009 at 4:21 AM, Robert Cimrman <cimr...@ntc.zcu.cz> wrote:
Yes, the site runs on moinmoin. However I am not convinced that moinmoin is the way to go, maybe also those pages could be based on sphinx, what do you think? We could maintain them in a git repository easily, so that the examples could be downloaded and tried-out by anyone.
That's true, after reading about the github pages I think moinmoin is just too much complexity. It's probably better just to keep them in the git repository.
ok. let's try this then.
I would also like to set-up a sphinx-based documentation site for sfepy, like [2] or [3], probably using github. Any volunteers out there? I have made some attempts to learn how to do it, but have currently no time to go on. And yes, new functions added to sfepy are documented and use the sphinx-compatible format, following the numpy's standards.
If no one else wants to volunteer, I can look into this. It would be good to get someone with more experience with github/Sphinx to give some starting pointers. This is how numpy guys do it:
http://projects.scipy.org/numpy/wiki/CodingStyleGuidelines http://svn.scipy.org/svn/numpy/trunk/doc/HOWTO_BUILD_DOCS.txt
I looked a bit into github. I was able to setup a repository on github fairly easy, so hosting the docs is no problem on there. But I'm not sure how to do regular web hosting from the repository yet. It is possible, see the notes below. I am open to alternatives, though - all I am persuaded is that we should use sphinx.
Ok, I'm in agreement. :) Github pages seem very cool.
Yes, they have a well-thought design.
I'm wondering a bit about the sphinx workflow. It seems like we should be able to autogenerate the docs from the sfepy source using sphinx. I was wondering if sphinx is already setup for sfepy, or should I work on that first? Once we get sphinx setup, can we just git pull sfepy, build the doc pages w/ sphinx, and the git push them to the documentation site? I'll try playing with the numpy source, so thanks for the Sphinx is not setup for sfepy yet, so this is the first step to undertake. It would be great if you could give it a shot!
The site [2] says how to have both the source code and the documentation in the same directory, but without unwanted interference, see the 'Project Pages' section.
I have also some advice from Ondrej, I will post it here on Monday, as I that information is on my workplace computer only...
Ok, great! So I have founded the information - a success story [1] :), and how to setup github pages [2].
[1] http://lists.xiph.org/pipermail/theora/2009-June/002328.html [2] http://pages.github.com/
Ok, I think I'll try to follow Ondrej's example for python-theora to setup the Sphinx doc. Hopefully all goes smoothly!
Great! This would really help a lot, thank you.
cheers, r.
PS: This time-lagged discussion is rather slow, I have to get up early one day, or stay till night at work :)