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.
