Hi Ben, Very good feedback, and I agree.
My intention is to use the PythonDoc Trac macro to integrate PythonDoc api output on the trac wiki. Hopefully, regularly available API docs will encourage people to work on the docstrings some more. PythonDoc allows you to produce almost any kind of output (it produces an XML infoset based on your python source). If anyone would like to produce a nicer bit of output, I'd be happy to use it! Kevin On Sep 3, 2006, at 3:49 PM, Ben Sizer wrote: > > I didn't see this mentioned anywhere else, so I thought I'd bring it > up. > > A lot of effort seems to be getting put into the tutorials, and into > the various 'how to do X' mini tutorials. The Getting Started guide is > really just yet another tutorial. But one major thing seems to be > forgotten; the API reference is woefully lacking, and I don't hear > about anybody attempting to fix it. It's not surprising that it's been > relegated to the bottom of the list. Talk of migrating docs to a wiki > seems to emphasise that this has flown beneath the radar. I know we > live in an age of screencasts and so on, but that doesn't change the > fact that the average programmer probably uses reference material far > more than they'll use tutorials. Yet we're apparently neglecting that > reference material. > > If you look at the API Reference page, you get a screen which is > pretty > useless - a list of subpackages and modules, many of which seem to be > for internal use, none of which have any sort of description. Worse > still, all you get is this top-down view; there's no index for a > bottom-up search, which is probably what most users are going to want. > > If you click on a module, eg. controllers, you get shown a lot of > private functions which shouldn't really be in the docs, and a lot of > poorly documented functions. expose() is reasonably well documented, > although even that has one big problem, which is pretty much witnessed > throughout - there are no examples. Even if you've got this far, and > seen which parameters you can pass in, working out what types are > expected is often a case of guesswork. > > So, let me summarise... the main problems in my humble opinion are: > > - No 'table of contents' that is organised in a usable manner > - No index > - No or very few usage examples > - Private functions need removing > > In theory, this shouldn't be that big a problem to fix: Turbogears > seems to actually have very few public classes and methods which the > end user needs to know about. They just need detailing in an > exhaustive > way, rather than spreading information about their capabilities > throughout 3 or 4 different tutorials. > > I really think that the MSDN docs are a 1st class example to follow > here. Each function has its own page, stating which module or object > it's from, what parameters it takes and what type they are, what it > returns, any remarks on how the function operates, and an example of > how the function would typically be used in context. I appreciate that > all that might be a little much for a Python docstring, but that just > emphasises the limitations of auto-generated docs really. > > Comments welcome. > > -- > Ben Sizer > > > > -- Kevin Dangoor TurboGears / Zesty News email: [EMAIL PROTECTED] company: http://www.BlazingThings.com blog: http://www.BlueSkyOnMars.com --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears" 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/turbogears -~----------~----~----~----~------~----~------~--~---
