I agree.. lets vote to ratify the vote that we made about the vote on ratifying the votes of this voting session.
As I am diving deeper into gluon, I would love to help contribute to documentation. Morover I am interested in documentation for plug-ins/modules, since I am developing plugin-central, this would be of benefit to include the auto-documentation along with plug-in uploads. -Thadeus On Sat, Dec 5, 2009 at 10:23 AM, Yarko Tymciurak <resultsinsoftw...@gmail.com> wrote: > On Dec 4, 9:45 am, mdipierro <mdipie...@cs.depaul.edu> wrote: >> Hi Dimitri, >> >> A few months back, Hans, Tim, Jonathan helped port most (if not all) >> the docstrings to Sphinx. Tim also wrote a script to generate Sphinx >> documentation from the docstrings (which in web2py/doc/ > > Yes - Tim nicely proposed a system of minimum documentation per > function; > > I slightly modified the build structure Tim put up, and started on one > gluon file, and found answering the questions necessary for > documenting the functions was often hard (because what the functions > did was not clear enough, or dependencies were not). > > I spent a _lot_ of time on one file, then gave up; current epydoc's > content are a level beneath the standards Tim suggested (http:// > projects.scipy.org/numpy/wiki/CodingStyleGuidelines) > > In particular, the sections this recommends - and which I > wholeheartedly supported, particularly a meaningful subset to get > web2py started on the path to staying "well documented" was this > outline (for example) for functions: > > 1. summary > 2. extended summary (optional) > 3. see also > 4. references > 5. examples > > Part of summary was to include methods: signature (parameters, > defaults, error handling), Wirfs-Brock basic CRC info (what the > function / class responsibilities are [behaviors/data], what it > depended on; who was known to depend on it. > > This information proved hard to pull together. > > So, this call - while welcomed - is not a technical / "who will do the > work" issue, rather one of getting to the structure which Tim > suggested (what does it realistically take?), a clear listing of what > is needed for standard documentation, and probalby for starters (as > recent "wtf" comments point out) a simpler annotation / commenting > of the code to HELP get this started. > > What is at stake: > > A fundamental standard for web2py. > Understanding what parts of the system are intended to do will provide > a path to peer reviews, and provide a consistent standard for modules, > additions from others. > > Generating "compiled" web2py documentation, both on the gluon / core > methods, and on contributed components, will result in consistent, up- > to-date documentation --- something that has repeatedly been requested > by the community. > > Since this (sphinx effort) ground to a halt, I would point out that: > > -- I believe Sphinx continues to be a good vehicle for auto-generated > documentation about a "current" web2py, with changes and contribution > (DenesL has back-filled this with persistent posts in this group w/ > new features since the last book); > > -- I believe the recent discussions on commenting the code is an > IMPORTANT BRIDGE to getting to the documentation standards that we > will be able to keep to and maintain (and where our first effort > should go) > > -- I believe that numpy may have more stringent reasons for > documentation; we should get a small web2py users team together to > identify the following: > > -- what should the web2py doc / testcase standards be which will > facilitate uniform and current documentation; > -- what (if any) smaller, less ambitious subset of the above should > be implemented first, so that some uniform documentation can be > delivered which is still useful (but not up to what we want) in the > interim; a transition plan to the final should be in place; > > -- I believe the doc standards should apply to gluon and contrib > first; > -- I believe applications should be held to the documentation > standards, and welcome and admin and examples should be the first to > implement / test these; > -- I believe modules and plugins should be held to the documentation > standards; > -- The minimum format for [a] gluon and core contributions, [b] > applications, and [c] plugins and modules may slightly vary, but > should be uniform enough that they will generate a coherent, > consistent document; > -- That any web2py installation should include an app which will > generate (script) documents for a particular installation: > --- one for admins (core), > --- one for app developers and maintainers (core + plugins & > modules and apps), > --- one for users (user level app helps / faq). > > In this way, any web2py installation will have a starting set of > documentation that will be current to the configuration and > contributions that installation picked. > > Perhaps for user FAQ / HELP, this should be a module which starts it's > info from static data (Sphinx), but is extensible from use (which > would give the developer a way to review and improve his/her design), > and a user-submitted, application specific "ticket" system). This > would be a useful module (and can wait until the basic documentation > standards, and generation are in place). > > Perhaps we can extend the "static" nature of the sphinx docs in some > way to collect comments for a particular doc. > > Finally, I think we should start by outline / commenting the basic > gluon and contrib sets - perhaps have a comment standard so we can > extract initial info which to start the doc process from. > > Your thoughts? > > Regards, > - Yarko >> >> Than this effort stopped. The goal should be that of improving the >> docstrings and add references so that generated documentation does not >> contain errors, is easy to navigate, and contains a decent into page. >> This could become a replacement for epydoc. >> >> The book is not a community effort (although the community is involved >> with proof-reading and translations) and it will stay in latex for >> now. Nevertheless you can take parts of the book, convert them to >> sphinx and use them to improve the docstrings. >> >> Massimo >> >> On Dec 4, 8:50 am, Dmitri Zagidulin <dzagidu...@gmail.com> wrote: >> >> >> >> > Just to clarify - is the conversation here about moving the main >> > manual (http://www.web2py.com/examples/default/docs) to Sphinx? >> > Or a different set of docs, auto-generated from the code comments or >> > something like? >> >> > In any case, I'd be willing to help work on it. >> >> > On Nov 23, 10:28 am, mdipierro <mdipie...@cs.depaul.edu> wrote: >> >> > > We have had some discussion about moving the documentation to Sphinx. >> > > Months have passed and there has been no progress. I personally do not >> > > mind epydoc but some of you really liked Sphinx. >> >> > > If you know Sphinx and want web2py to use it, please help us. >> >> > > Massimo > > -- > > You received this message because you are subscribed to the Google Groups > "web2py-users" group. > To post to this group, send email to web...@googlegroups.com. > To unsubscribe from this group, send email to > web2py+unsubscr...@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/web2py?hl=en. > > > -- You received this message because you are subscribed to the Google Groups "web2py-users" group. To post to this group, send email to web...@googlegroups.com. To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/web2py?hl=en.
