Hello guys, you move fast. I was on the weekend and Massimo uploaded the file. Then already 2-3 comments. Let me give my comments as the guilty person.
I am doing some tweaking here: https://code.launchpad.net/~web2py/web2py/web2py-sphinx This is owned by the team. So anyone being part of https://code.launchpad.net/~web2py can commit / push changes. Once the Sphinx stuff gets mature, we can merge it with the main tree. I do not have experience in mutal development using LP. So far, I just make may changes and push up there. > 1. core developers maintains docstrings carefully, synchronize them > with code change. Correct. > 2. an easy way (sphinx?) to generate all doc into decent html, release > them as built-in official documents THis can be done as post-commit hook with DVCS or by a separate shell script. > 3. web2py users reads the documents, no need to dive into docstring in > source code so much. (For example, I used python for years but never > read comments (if any) in its source code. Do you?) The users shall also contribute to the docs be reviewing and correcting or extending. > Even for developers, there is still issue to be addressed. If more > than one core developer (Massimo) will update the docstring, how do > they collaborate with each other? I smell frequent source code > conflict here. After all, svn etc. are not like a wiki. Only wiki is > designed for many people to work on open documents. I do not expect huge conflicts due to the reason that Massimo is mainly working on code. So any contribution to the docstrings will be complementary. But the numpy/scipy community has created a online editor for this pupose here: * online editor: http://docs.scipy.org/numpy/Front Page * the source: https://code.launchpad.net/~pauli-virtanen/scipy/pydocweb * then, there is a Sphinx GSoC project for creating an online version: http://tosh.pl/gminick/gsoc/sphinx/ I will soon tell you how to build the html docs yourself. The bottom line is: 1) easy_install -U sphinx 2) cd web2py/doc 3) run make-doc_html.bat or make-doc_html.sh 4) the result will go to: web2py/applications/examples/static/sphinx This is desired by Massimo. I guess he will use this static path to include it in future versions of web2py. Please send any new docs in RST format. The recent thread on where to get help is included in the documentation overview: http://bazaar.launchpad.net/%7Eweb2py/web2py/web2py-sphinx/annotate/head%3A/doc/source/docs.rst You may take this as example. The best introduction to RST that convinced me is here: http://sphinx.pocoo.org/rest.html You can use the following editors which have a preview mode for RST format: * Emacs: see docutils page * Gedit (Linux): http://textmethod.com/wiki/ReStructuredTextToolsForGedit * Ulipad (Win): http://code.google.com/p/ulipad/ If you want to contribute to the sphinx docs but cannot access Launchpad, send me the file to my mail. I hope that we can smoothly improve the documentation situation. Note: I may not work on this on a daily basis but keep an eye on it. If you wanna make sure that I get the message about Sphinx, please put my mail in CC . The next on the todo list: 1) activate numpy extension (know how!) 2) correct docstrings 3) add more hand written documentation. @massimo: can you have a export of the wiki? Then, users could edit the wiki pages and I would include your RST export in the Sphinx docs. What do you think? Regards, Timmie P.S.: Please be patient. LP needs some time to update its pages after a push. --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "web2py Web Framework" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/web2py?hl=en -~----------~----~----~----~------~----~------~--~---
